feat(api): declare oauth2 security scheme for MCP per-user auth#2961
Merged
Conversation
Hosted MCP (Speakeasy Gram) only surfaces a customer-facing 'Sign in with Comp AI' flow and forwards each user's bearer token to the API when the OpenAPI spec declares an oauth2 scheme. With only the X-API-Key scheme, Gram would call the API with one shared key for every user, bypassing the per-user/per-org RBAC the API already enforces. Adds an oauth2 (authorization code) scheme pointed at the better-auth MCP authorization server and offers it alongside the API key on every authenticated operation (OR semantics — either credential satisfies a request, so existing API-key integrations are unaffected). Centralized in applyPublicOpenApiMetadata so all three spec-generation paths stay consistent; committed openapi.json regenerated (verified byte-identical to a GEN_OPENAPI=1 run). Once synced to Gram, oauth2SecurityCount>0 unlocks the External/Proxy OAuth wizard. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
2 Skipped Deployments
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
|
🎉 This PR is included in version 3.66.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
This unblocks keyless, per-user auth for the hosted MCP (Speakeasy Gram).
I traced Gram's source: it picks the credential it sends to our backend from the spec's security scheme. With only the
X-API-Keyscheme, Gram would call our API with one shared key for every MCP user — bypassing the per-user/per-org RBAC the API already enforces. Gram also only shows the customer-facing OAuth wizard when the spec advertises an oauth2 scheme (oauth2SecurityCount > 0); until then it offers only "Gram OAuth" (internal Gram-org members).What
oauth2(authorization code) security scheme pointed at the better-auth MCP authorization server (/api/auth/mcp/authorize+/token).applyPublicOpenApiMetadataso all three spec-generation paths (main.ts,gen-openapi.spec.ts,openapi-docs.spec.ts) stay consistent.openapi.json— verified byte-identical to a realGEN_OPENAPI=1run (935 insertions, 0 deletions; 306/306 API-key ops now also offer oauth2).How it fits the rollout
Once merged, the existing
gram-syncCI pushes the updated spec →oauth2SecurityCountflips above 0 → the External/Proxy OAuth wizard unlocks in Gram. Next steps (Gram-side): set the MCP server Public, run the OAuth wizard pointed at better-auth, set the stagingGRAM_OAUTH_*env vars.Tests
openapi-docs.spec.tscases: asserts the oauth2 scheme exists with the right endpoints, every API-key op also offers oauth2, and oauth2 is never on a non-API-key (public) op.openapi-docs.spec.tsgreen (5/5).Heads-up
Speakeasy SDK generation consumes this spec; it'll see the new oauth2 scheme (additive). The authorization-code flow is for interactive/MCP clients — existing API-key SDK usage is unchanged.
🤖 Generated with Claude Code
Summary by cubic
Enables per-user OAuth for hosted MCP (Speakeasy Gram) by declaring an
oauth2authorization-code security scheme in the public OpenAPI spec, alongside the existing API key. This unlocks Gram’s OAuth wizard and keeps current API-key integrations working.oauth2authorization code scheme pointing to/api/auth/mcp/authorizeand/api/auth/mcp/token.oauth2on all API-key–gated operations (OR semantics: API key or OAuth token).applyPublicOpenApiMetadatato keep all spec-generation paths consistent.packages/docs/openapi.json.Written for commit e906b6d. Summary will update on new commits.
Review in cubic