DOCS-1534 - MCP and OAuth docs by kimsauce · Pull Request #6574 · SumoLogic/sumologic-documentation

kimsauce · 2026-04-11T09:49:09Z

Purpose of this pull request

This pull request improves the MCP server doc (currently in preview) and introduces the OAuth doc. Checked structure, clarity, and deployment endpoint guidance. Key changes include:

MCP documentation (mcp-server.md):

Add ChatGPT as a supported MCP client with complete setup instructions
Add Authorization Code OAuth flow for ChatGPT and Claude Code
Restructure authentication sections to be client-specific (under each client) rather than global
Ensure parallel structure across all three client configuration sections
Add tip about discovering token endpoint programmatically
Add inline comment clarifying deployment endpoint in reconnection script
Consolidate redundant client lists in intro
Update status from "Closed Preview" to "Private Preview"

OAuth documentation (oauth.md):

Update page title from "OAuth" to "OAuth Client Setup"
Add deployment endpoint clarifications throughout (with examples like service.sumologic.com, service.us2.sumologic.com, service.eu.sumologic.com)
Consolidate redundant intro content
Improve scannability with simplified terminology

Select the type of change

Minor Changes - Typos, formatting, slight revisions
Update Content - Revisions, updating sections
New Content - New features, sections, pages, tutorials
Site and Tools - .clabot, version updates, maintenance, dependencies, new packages for the site (Docusaurus, Gatsby, React, etc.)

Ticket (if applicable)

https://sumologic.atlassian.net/browse/DOCS-1534

Updates the MCP server documentation to include ChatGPT as a supported client and adds comprehensive setup instructions for the Authorization Code OAuth flow. Restructures authentication section to clearly distinguish between Authorization Code flow (for ChatGPT and Claude Code) and Client Credentials flow (for VS Code and Claude Code). Key changes: - Add ChatGPT setup instructions with UI-based OAuth client creation - Add Authorization Code flow setup for Claude Code - Update status from "Closed Preview" to "Private Preview" - Reorganize authentication section with comparison table - Use AuthorizationCodeClient terminology to match UI Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add prominent note callout before Step 3 curl examples to make deployment URL requirements clearer for Preview customers reading top-to-bottom. Addresses feedback that deployment info wasn't immediately obvious. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Update OAuth doc title to "OAuth Client Setup" - Restructure MCP authentication sections to be client-specific - Add deployment endpoint clarifications throughout both docs - Add tip about discovering token endpoint programmatically - Consolidate redundant content in OAuth intro Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Implements feedback from auth-code-flow-docs-update-review.pdf: OAuth documentation changes: - Remove MCP server parenthetical reference from intro - Change "your application" to "an external application" in Authorization Code flow intro for clarity - Update token expiration to reference expires_in property instead of hardcoded "1 hour" - Update refresh token rotation language (always rotates, not configurable) - Remove personal access key prerequisite (OAuth clients now created via UI) - Add UI-first approach for service account ID retrieval with API as alternative - Replace curl-based OAuth client creation with UI steps for Client Credentials flow - Preserve API examples in collapsible sections for advanced users - Fix highlighted field in service account JSON response (id not modifiedAt) MCP server documentation changes: - Change "external copilots and proprietary models" to "MCP clients (external AI models)" - Remove em dashes and improve sentence structure per style guide Style fixes: - Remove all em dashes per Sumo Logic style guide - Fix hyphenation (MCP-clients → MCP clients) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ganano

Took a first pass through the docs.

ganano · 2026-05-04T22:55:25Z

+1. Copy the **Redirect URL** shown in the dialog. You'll use this when [creating your OAuth client in Sumo Logic](/docs/manage/security/oauth#authorization-code-flow).
+1. In Sumo Logic, [create an OAuth client using the Authorization Code flow](/docs/manage/security/oauth#authorization-code-flow) with the redirect URL from ChatGPT.
+1. Return to ChatGPT's Create App dialog and enter:
+   * **MCP Server URL**: `https://mcp.sumologic.com/mcp`


Probably worthwhile to make sure its clear about the deployment specific domains here.

ganano · 2026-05-04T22:55:43Z

+     --client-id "<client-id>" \
+     --callback-port 8888 \
+     --client-secret \
+     sumo-logic "https://mcp.sumologic.com/mcp"


Same here about the domains.

ganano · 2026-05-04T22:57:09Z

+   ```
+1. Launch Claude Code.
+   ```bash
+   cd /path/to/your/project


This might mislead people based on the above "claude mcp add" command.

The above command only adds it for claude in the directory that the command was run. So, if the user goes to another directory, then the MCP server will not show up.

To add it globally to claude so that the directory doesn't matter, then the command needs to include the "--scope user" option.

ganano · 2026-05-04T23:28:41Z

+### Authentication

-Use the `scope` parameter to assign specific scopes in your request, separated by spaces, not commas (for example, `"scope=viewUsersAndRoles manageCollectors runLogSearch"`).
+Claude Code supports two OAuth 2.0 authentication flows:


My opinion and I'm curious others thoughts, but we should only cover the Authorization Code Flow for Claude. I can't see any reason why someone would use either of the Client Credentials setups once we have Authorization Code Flow released for Claude.

To be clear, we will need to leave the Client Credentials sections for VS Code because as of yet, I haven't figured out how to make that work with Authorization Code Flow.

ganano · 2026-05-05T00:11:57Z

+The token endpoint URL varies by deployment. To discover it programmatically (for example, in automation scripts), query the Authorization Server Metadata for your deployment:
+
+```bash
+curl https://service.sumologic.com/.well-known/oauth-authorization-server


Similar question about the domains...

Maybe we should have a matrix with all of the deployments and domains?

ganano · 2026-05-05T00:13:09Z

+
+## Security best practices
+
+* **Protect client secrets**. Store client secrets securely using environment variables, secrets management systems, or encrypted configuration files. Never commit secrets to version control.


The clientSecret isn't a risk in the Authorization Code Flow.

ganano · 2026-05-05T00:16:03Z

+1. Find the OAuth client you want to revoke.
+1. Click **Delete** or **Deactivate** (depending on UI options available).
+
+For Client Credentials flow, you can also deactivate or delete the associated service account, which will immediately revoke all access for OAuth clients using that service account.


I think revoking the Authorization Consent will have a similar impact in Authorization Code Flow setup in that the next refresh of the token will fail, right? cc: @kdwink

ganano · 2026-05-05T00:16:56Z

+Yes. OAuth access tokens work with all Sumo Logic APIs. Include the access token in the `Authorization` header as a Bearer token:
+
+```bash
+curl https://service.sumologic.com/api/v1/users \


api.sumologic.com

ganano · 2026-05-05T00:18:19Z

+</details>
+
+<details>
+<summary>What happens if I change a service account's roles?</summary>


We should probably add a similar question for what happens when a users roles change with Authorization Code Flow.

@kdwink can probably provide a good explanation as he just updated how this works.

kimsauce · 2026-05-05T01:56:49Z

Hi @ganano , thanks for the thorough review! Here's what I addressed based on your feedback:

docs/api/mcp-server.md

Removed the Client Credentials flow sections from the Claude Code CLI setup. Auth Code flow is now the only documented path for Claude. VS Code remains on Client Credentials.
Added --scope user / --scope project options to the claude mcp add command in the Auth Code flow setup, matching the pattern used for Client Credentials. Updated the launch step to note that user scope (recommended) works from any directory.
Added the deployment domain tip after the MCP Server URL in the ChatGPT section, consistent with the tips that already existed for VS Code and the (now-removed) Client Credentials options.

docs/manage/security/oauth.md

Simplified the Auth Code flow section per your suggestion... removed the manual curl steps (Authorize, Exchange, Refresh) and replaced them with a note about the .well-known/oauth-authorization-server discovery endpoint, and a tip about the permissions intersection model (user roles ∩ client scopes ∩ requested scopes).
Changed service.sumologic.com → api.sumologic.com in the API call examples (token usage example and the APIs FAQ), and added deployment tips pointing to the endpoints reference page.
Updated the deployment placeholder in the "Discovering endpoints programmatically" tip to be consistent with the rest of the doc.
Scoped the "Protect client secrets" security practice to call out Client Credentials as the higher-risk case; noted that clientSecret in Auth Code flow carries less risk.
Updated the revoke access FAQ to cover Auth Code flow: revoking Authorization Consent causes the next token refresh to fail (current token stays valid until expiry).
Added a new FAQ: "What happens if a user's roles change in Authorization Code flow?" — covers how role changes take effect at next token refresh for both restrictions and expansions.

One thing I wasn't sure about, your line 49 comment mentioned adding a tip about how permissions are calculated specifically for Auth Code. I added that as a :::tip block in the "Complete the OAuth flow" section. Let me know if the wording captures it correctly or if the intersection should be described differently.

…docs - mcp-server.md: remove Client Credentials sections from Claude Code CLI setup (Auth Code flow only); add --scope user/project options to claude mcp add command; add deployment domain tips to ChatGPT and Claude sections - oauth.md: simplify Auth Code flow (replace curl steps with OAuth 2.1 spec pointer and permissions intersection tip); fix API call domains to api.sumologic.com; update security practices, revoke FAQ, and add user roles change FAQ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ganano

Couple of minor comments, but otherwise lgtm.

Approving to remove myself from the review cycle.

ganano · 2026-05-06T22:01:56Z

+
+This flow uses interactive browser-based authentication. Users authorize an external application to access Sumo Logic on their behalf, and the application receives an access token to make API requests.
+
+### Create an OAuth client


I noticed that for the Client Credentials it lists the prerequisite of being an Administrator. That is true for the Authorization Code scenario as well.

ganano · 2026-05-06T22:04:16Z

+* The scopes assigned to the OAuth client.
+* The scopes requested in the authorization request.
+
+If a user's roles are restricted, their effective OAuth permissions are reduced at the next token refresh. If roles are expanded, the new permissions become available at the next token refresh.


Probably worth noting about if the permissions are expanded the the new permissions will become available on the next token refresh only with the permissions that have previously been "consented" to. If the permissions expand beyond the "consented", then to get a token with those permissions will require re-authenticating to the authorization server.

kimsauce requested review from JV0812, amee-sumo, jpipkin1 and mafsumo as code owners April 11, 2026 09:49

cla-bot Bot added the cla-signed Contributor approved, listed in .clabot file label Apr 11, 2026

kimsauce self-assigned this Apr 11, 2026

kimsauce changed the title ~~DOCS-1534 - Add ChatGPT support and Authorization Code OAuth flow to MCP server docs~~ DOCS-1534 - Add ChatGPT support and 3LO flow to MCP docs Apr 11, 2026

kimsauce marked this pull request as draft April 11, 2026 09:51

kimsauce and others added 4 commits April 13, 2026 04:56

Merge remote-tracking branch 'origin/main' into DOCS-1534

dc47f83

split MCP and OAuth

94b7c5a

kimsauce changed the title ~~DOCS-1534 - Add ChatGPT support and 3LO flow to MCP docs~~ DOCS-1534 - Improve MCP and OAuth documentation structure and clarity Apr 15, 2026

kimsauce changed the title ~~DOCS-1534 - Improve MCP and OAuth documentation structure and clarity~~ DOCS-1534 - Add 3LO/OAuth doc, improve/update MCP doc Apr 15, 2026

kimsauce requested review from DDeC7 and ganano April 15, 2026 03:57

kimsauce and others added 2 commits April 14, 2026 21:00

Fix broken link in MCP server doc

825ca71

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge branch 'main' into DOCS-1534

05f99ed

kimsauce changed the title ~~DOCS-1534 - Add 3LO/OAuth doc, improve/update MCP doc~~ DOCS-1534 - Add Auth doc, update MCP doc Apr 17, 2026

kimsauce added doc:update Revisions and updates to content doc:new New section or topic to content labels Apr 17, 2026

kimsauce requested a review from kdwink April 17, 2026 09:20

kimsauce and others added 3 commits April 17, 2026 02:54

Merge branch 'main' into DOCS-1534

de84cf1

oauth = preview

163230a

kimsauce changed the title ~~DOCS-1534 - Add Auth doc, update MCP doc~~ DOCS-1534 - MCP and OAuth docs Apr 17, 2026

ganano reviewed May 5, 2026

View reviewed changes

Merge branch 'main' into DOCS-1534

9254040

kimsauce marked this pull request as ready for review May 5, 2026 02:03

ganano approved these changes May 6, 2026

View reviewed changes

kimsauce removed the doc:update Revisions and updates to content label May 6, 2026


		## Security best practices

		* Protect client secrets. Store client secrets securely using environment variables, secrets management systems, or encrypted configuration files. Never commit secrets to version control.


		This flow uses interactive browser-based authentication. Users authorize an external application to access Sumo Logic on their behalf, and the application receives an access token to make API requests.

		### Create an OAuth client

Conversation

kimsauce commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose of this pull request

Select the type of change

Ticket (if applicable)

Uh oh!

ganano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kimsauce commented May 5, 2026

Uh oh!

ganano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kimsauce commented Apr 11, 2026 •

edited

Loading