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

example-docker-compose.yaml

@@ -306,6 +306,8 @@ services:
     env_file:
       - /root/.env
     environment:
+      MCP_OAUTH_ISSUER_URL: ${MCP_OAUTH_ISSUER_URL:-}
+      MCP_RESOURCE_SERVER_URL: ${MCP_RESOURCE_SERVER_URL:-}
       BRAINAPI_PLUGINS: ${BRAINAPI_PLUGINS:-}
       PLUGIN_REGISTRY_URL: ${PLUGIN_REGISTRY_URL:-}
       PLUGIN_PUBLISHER_ID: ${PLUGIN_PUBLISHER_ID:-}

src/services/mcp/app.py

@@ -1,5 +1,6 @@
 import logging
 import os
+from contextlib import asynccontextmanager
 from pathlib import Path
 
 import dotenv
@@ -11,7 +12,7 @@
 _project_root = Path(__file__).resolve().parent.parent.parent.parent
 dotenv.load_dotenv(_project_root / ".env")
 
-from src.services.mcp.main import auth_token_var, mcp
+from src.services.mcp.main import auth_token_var, mcp, oauth_provider
 
 PLUGINS_DIR = Path(os.getenv("PLUGINS_DIR", str(_project_root / "plugins")))
 
@@ -92,10 +93,17 @@ async def __call__(self, scope, receive, send):
                 token = brainpat.decode()
             else:
                 raw = (headers.get(b"authorization") or b"").decode()
+                bearer = None
                 if raw.startswith("Bearer: "):
-                    token = raw.removeprefix("Bearer: ").strip() or None
+                    bearer = raw.removeprefix("Bearer: ").strip() or None
                 elif raw.startswith("Bearer "):
-                    token = raw.removeprefix("Bearer ").strip() or None
+                    bearer = raw.removeprefix("Bearer ").strip() or None
+                if bearer:
+                    if oauth_provider:
+                        pat = oauth_provider.get_pat_for_access_token(bearer)
+                        token = pat if pat else bearer
+                    else:
+                        token = bearer
             auth_token_var.set(token)
         await self.app(scope, receive, send)
 
@@ -105,10 +113,21 @@ async def _health(_request):
 
 
 async def _mcp_info(_request):
-    return JSONResponse(
-        {"service": "brainapi-mcp", "streamable_http": True, "path": "/mcp"},
-        status_code=200,
-    )
+    body = {
+        "service": "brainapi-mcp",
+        "streamable_http": True,
+        "path": "/mcp",
+    }
+    if oauth_provider:
+        body["oauth"] = True
+        body["oauth_consent_path"] = "/mcp-oauth/consent"
+    return JSONResponse(body, status_code=200)
+
+
+@asynccontextmanager
+async def _lifespan(app):
+    async with _mcp_app.router.lifespan_context(_mcp_app):
+        yield
 
 
 _custom_routes = [
@@ -119,5 +138,5 @@ async def _mcp_info(_request):
 app = Starlette(
     routes=_custom_routes + list(_mcp_app.routes),
     middleware=[Middleware(AuthContextMiddleware)],
-    lifespan=_mcp_app.router.lifespan_context,
+    lifespan=_lifespan,
 )

src/services/mcp/main.py

@@ -10,10 +10,16 @@
 """
 
 import asyncio
+import html
+import os
 from contextvars import ContextVar
 from typing import Any
 
 from mcp.server import FastMCP
+from mcp.server.auth.settings import AuthSettings, ClientRegistrationOptions
+from pydantic import AnyHttpUrl, AnyUrl
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, RedirectResponse
 
 from src.core.instances import (
     data_adapter,
@@ -22,13 +28,135 @@
     vector_store_adapter,
 )
 from src.lib.neo4j.client import _neo4j_client
+from src.services.mcp.oauth_provider import BrainapiMcpOAuthProvider
 from src.services.mcp.utils import guard_brainpat
 from src.utils.vector_search import VectorSearchFacade
 
 auth_token_var: ContextVar[str | None] = ContextVar("auth_token", default=None)
 vector_search = VectorSearchFacade(vector_store_adapter)
 
-mcp = FastMCP("brainapi-mcp", stateless_http=True, host="0.0.0.0")
+_oauth_issuer = os.getenv("MCP_OAUTH_ISSUER_URL", "").strip()
+_oauth_resource = os.getenv("MCP_RESOURCE_SERVER_URL", "").strip()
+if _oauth_issuer and not _oauth_resource:
+    _oauth_resource = _oauth_issuer.rstrip("/") + "/mcp"
+
+_oauth_scopes = [
+    s for s in os.getenv("MCP_OAUTH_SCOPES", "brainapi").strip().split() if s
+]
+if not _oauth_scopes:
+    _oauth_scopes = ["brainapi"]
+
+_access_ttl = int(os.getenv("MCP_OAUTH_ACCESS_TOKEN_TTL", "3600"))
+_refresh_ttl_raw = os.getenv("MCP_OAUTH_REFRESH_TOKEN_TTL", "").strip()
+_refresh_ttl = int(_refresh_ttl_raw) if _refresh_ttl_raw else None
+_code_ttl = int(os.getenv("MCP_OAUTH_AUTH_CODE_TTL", "600"))
+
+oauth_provider: BrainapiMcpOAuthProvider | None = None
+if _oauth_issuer:
+    oauth_provider = BrainapiMcpOAuthProvider(
+        issuer_url=_oauth_issuer,
+        resource_server_url=_oauth_resource,
+        valid_scopes=_oauth_scopes,
+        access_token_ttl_seconds=_access_ttl,
+        refresh_token_ttl_seconds=_refresh_ttl,
+        auth_code_ttl_seconds=_code_ttl,
+    )
+    _doc_url = os.getenv("MCP_OAUTH_SERVICE_DOCUMENTATION_URL", "").strip()
+    mcp = FastMCP(
+        "brainapi-mcp",
+        stateless_http=True,
+        host="0.0.0.0",
+        auth_server_provider=oauth_provider,
+        auth=AuthSettings(
+            issuer_url=AnyHttpUrl(_oauth_issuer),
+            resource_server_url=AnyHttpUrl(_oauth_resource),
+            service_documentation_url=AnyHttpUrl(_doc_url) if _doc_url else None,
+            client_registration_options=ClientRegistrationOptions(
+                enabled=True,
+                valid_scopes=_oauth_scopes,
+                default_scopes=_oauth_scopes,
+            ),
+        ),
+    )
+else:
+    mcp = FastMCP("brainapi-mcp", stateless_http=True, host="0.0.0.0")
+
+
+if oauth_provider:
+
+    async def _mcp_oauth_consent(request: Request) -> HTMLResponse | RedirectResponse:
+        if request.method == "GET":
+            q = request.query_params
+            client_id = q.get("client_id") or ""
+            redirect_uri = q.get("redirect_uri") or ""
+            code_challenge = q.get("code_challenge") or ""
+            scope = q.get("scope") or " ".join(_oauth_scopes)
+            resource = q.get("resource") or ""
+            state = q.get("state") or ""
+            if not (client_id and redirect_uri and code_challenge):
+                return HTMLResponse("Missing OAuth parameters", status_code=400)
+            client = await oauth_provider.get_client(client_id)
+            if not client:
+                return HTMLResponse("Unknown client_id", status_code=400)
+            esc = html.escape
+            form = f"""<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Authorize BrainAPI MCP</title></head>
+<body>
+<h1>Connect to BrainAPI</h1>
+<p>Enter your BrainPAT (personal access token for your brain). This authorizes the MCP client to act with that token.</p>
+<form method="post" action="/mcp-oauth/consent">
+<input type="hidden" name="client_id" value="{esc(client_id)}">
+<input type="hidden" name="redirect_uri" value="{esc(redirect_uri)}">
+<input type="hidden" name="code_challenge" value="{esc(code_challenge)}">
+<input type="hidden" name="scope" value="{esc(scope)}">
+<input type="hidden" name="resource" value="{esc(resource)}">
+<input type="hidden" name="state" value="{esc(state)}">
+<label for="brainpat">BrainPAT</label>
+<input id="brainpat" name="brainpat" type="password" autocomplete="off" required style="width:100%;max-width:40em">
+<button type="submit">Authorize</button>
+</form>
+</body></html>"""
+            return HTMLResponse(form)
+
+        form = await request.form()
+        client_id = str(form.get("client_id") or "")
+        redirect_uri = str(form.get("redirect_uri") or "")
+        code_challenge = str(form.get("code_challenge") or "")
+        scope_str = str(form.get("scope") or "")
+        resource = str(form.get("resource") or "") or None
+        state = str(form.get("state") or "") or None
+        brainpat = str(form.get("brainpat") or "").strip()
+        if not (client_id and redirect_uri and code_challenge and brainpat):
+            return HTMLResponse("Missing fields", status_code=400)
+        client = await oauth_provider.get_client(client_id)
+        if not client:
+            return HTMLResponse("Unknown client", status_code=400)
+        if guard_brainpat(brainpat) is False:
+            return HTMLResponse("Invalid BrainPAT", status_code=401)
+        scopes = scope_str.split() if scope_str.strip() else list(_oauth_scopes)
+        for s in scopes:
+            if s not in _oauth_scopes:
+                return HTMLResponse("Invalid scope", status_code=400)
+        try:
+            ru = AnyUrl(redirect_uri)
+            ru = client.validate_redirect_uri(ru)
+        except Exception:
+            return HTMLResponse("Invalid redirect_uri", status_code=400)
+        code = oauth_provider.issue_auth_code(
+            client_id=client_id,
+            redirect_uri=ru,
+            code_challenge=code_challenge,
+            scopes=scopes,
+            resource=resource,
+            state=state,
+            brainpat=brainpat,
+        )
+        url = oauth_provider.redirect_after_consent(
+            redirect_uri=redirect_uri, code=code, state=state
+        )
+        return RedirectResponse(url, status_code=302)
+
+    mcp.custom_route("/mcp-oauth/consent", methods=["GET", "POST"])(_mcp_oauth_consent)
 
 
 @mcp.tool()