feat(mcp): optional MCP OAuth for Claude-compatible connectors

[ChrisCoder9000]

Summary

This adds optional OAuth for the BrainAPI MCP HTTP service so MCP clients (including Claude’s remote MCP connector) can follow the MCP authorization spec: protected resource metadata, dynamic client registration, PKCE authorization code flow, and Authorization: Bearer access tokens.

When OAuth is disabled (default, no env vars), behavior stays the same: MCP accepts BrainPAT or Authorization: Bearer <brainpat> as today.

How to enable

Set MCP_OAUTH_ISSUER_URL to the public HTTPS base URL of the MCP service (same host/port as uvicorn, no path), for example https://mcp.example.com.

Optional:

• MCP_RESOURCE_SERVER_URL: canonical MCP resource URL (defaults to {issuer}/mcp). Must match what clients send as the RFC 8707 resource parameter.
• MCP_OAUTH_SCOPES: space-separated scopes (default brainapi).
• MCP_OAUTH_ACCESS_TOKEN_TTL, MCP_OAUTH_REFRESH_TOKEN_TTL, MCP_OAUTH_AUTH_CODE_TTL: TTLs in seconds.
• MCP_OAUTH_SERVICE_DOCUMENTATION_URL: URL for OAuth server metadata service_documentation.

User flow

1. Client discovers metadata and registers (FastMCP built-in /.well-known/oauth-authorization-server, /register, /authorize, /token).
2. After /authorize, the user is redirected to /mcp-oauth/consent to enter BrainPAT; on success an auth code is issued and the client exchanges it for tokens.
3. MCP tools continue to use guard_brainpat: Bearer access tokens are mapped back to the BrainPAT supplied at consent.

Notes

• Token and code storage is in-memory (single process); restarts invalidate sessions. A follow-up could persist codes/tokens in Redis if needed.
• example-docker-compose.yaml documents the new env vars for the MCP service.

  

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dbcd9827-1857-40c2-ab66-7b873ce4b12d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/mcp-oauth-claude-c9d2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}