ops(brain): register brain MCP as a custom integration in claude.ai #21

New Issue

mathias · 2026-05-19T11:11:04Z

mathias commented

2026-05-19 11:11:04 +00:00

Context

OAuth client_credentials flow (hyperguild#5) shipped and is active in the live pod. OAUTH_CLIENT_ID=brain-mcp-claudeai and a random OAUTH_CLIENT_SECRET live in SOPS. Once claude.ai is configured, web sessions can call brain tools without the static-Bearer header that the UI doesn't expose.

Action

Pull the secret values:

sops -d ~/dev/AI/infra/k3s/apps/supervisor/secrets.enc.yaml | \
  grep -E 'OAUTH_CLIENT_(ID|SECRET)'

claude.ai → Settings → Integrations → Add custom MCP:
- URL: https://brain-mcp.d-ma.be/mcp
- Client ID: from step 1
- Client Secret: from step 1
Save. claude.ai fetches /.well-known/oauth-authorization-server, exchanges credentials, uses the issued bearer on /mcp.

Verification

In a fresh claude.ai conversation, tools/list should show the eight brain tools (brain_query, brain_write, brain_index, brain_tunnel, brain_ingest_raw, brain_ingest, brain_answer, brain_classify, session_log). A brain_query should return non-empty results.

Acceptance criteria

Integration registered, no errors on save
claude.ai /mcp lists all brain tools
A trivial brain_query round-trips
Verify the Dex JWT flow (existing claude.ai custom MCP if any) is NOT broken — both should coexist

## Context OAuth client_credentials flow (hyperguild#5) shipped and is active in the live pod. `OAUTH_CLIENT_ID=brain-mcp-claudeai` and a random `OAUTH_CLIENT_SECRET` live in SOPS. Once claude.ai is configured, web sessions can call brain tools without the static-Bearer header that the UI doesn't expose. ## Action 1. Pull the secret values: ```bash sops -d ~/dev/AI/infra/k3s/apps/supervisor/secrets.enc.yaml | \ grep -E 'OAUTH_CLIENT_(ID|SECRET)' ``` 2. claude.ai → Settings → Integrations → Add custom MCP: - **URL**: `https://brain-mcp.d-ma.be/mcp` - **Client ID**: from step 1 - **Client Secret**: from step 1 3. Save. claude.ai fetches `/.well-known/oauth-authorization-server`, exchanges credentials, uses the issued bearer on `/mcp`. ## Verification In a fresh claude.ai conversation, `tools/list` should show the eight brain tools (`brain_query`, `brain_write`, `brain_index`, `brain_tunnel`, `brain_ingest_raw`, `brain_ingest`, `brain_answer`, `brain_classify`, `session_log`). A `brain_query` should return non-empty results. ## Acceptance criteria - [ ] Integration registered, no errors on save - [ ] claude.ai `/mcp` lists all brain tools - [ ] A trivial `brain_query` round-trips - [ ] Verify the Dex JWT flow (existing claude.ai custom MCP if any) is NOT broken — both should coexist

mathias commented

2026-05-20 07:46:19 +00:00

Registered. OAuth flow verified end-to-end from koala before handoff:

$ curl https://brain-mcp.d-ma.be/.well-known/oauth-protected-resource
{"resource":"https://brain-mcp.d-ma.be","authorization_servers":["https://auth.d-ma.be"]}

$ curl https://brain-mcp.d-ma.be/.well-known/oauth-authorization-server
{"issuer":"https://brain-mcp.d-ma.be","token_endpoint":"https://brain-mcp.d-ma.be/oauth/token",
 "grant_types_supported":["client_credentials"],
 "token_endpoint_auth_methods_supported":["client_secret_post","client_secret_basic"]}

$ curl -u brain-mcp-claudeai:<secret> -d grant_type=client_credentials https://brain-mcp.d-ma.be/oauth/token
{"access_token":"...","token_type":"bearer"}

$ curl -H "Authorization: Bearer ..." -d '{"jsonrpc":"2.0","method":"initialize",...}' https://brain-mcp.d-ma.be/mcp
{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":{}},"protocolVersion":"2024-11-05",
 "serverInfo":{"name":"ingestion-brain","version":"0.1.0"}}}

The Authorization Server is brain-mcp itself (issuer = https://brain-mcp.d-ma.be), not Dex — brain-mcp's own /oauth/token endpoint implements client_credentials per ingestion/internal/oauth/token.go. Client secret validated against the SOPS-stored OAUTH_CLIENT_SECRET; on success the same static BRAIN_MCP_TOKEN is returned as the bearer (so the static-Bearer code path and the OAuth code path converge on the same token, just with two arrival routes).

Closes.

Registered. OAuth flow verified end-to-end from koala before handoff: ``` $ curl https://brain-mcp.d-ma.be/.well-known/oauth-protected-resource {"resource":"https://brain-mcp.d-ma.be","authorization_servers":["https://auth.d-ma.be"]} $ curl https://brain-mcp.d-ma.be/.well-known/oauth-authorization-server {"issuer":"https://brain-mcp.d-ma.be","token_endpoint":"https://brain-mcp.d-ma.be/oauth/token", "grant_types_supported":["client_credentials"], "token_endpoint_auth_methods_supported":["client_secret_post","client_secret_basic"]} $ curl -u brain-mcp-claudeai:<secret> -d grant_type=client_credentials https://brain-mcp.d-ma.be/oauth/token {"access_token":"...","token_type":"bearer"} $ curl -H "Authorization: Bearer ..." -d '{"jsonrpc":"2.0","method":"initialize",...}' https://brain-mcp.d-ma.be/mcp {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":{}},"protocolVersion":"2024-11-05", "serverInfo":{"name":"ingestion-brain","version":"0.1.0"}}} ``` The Authorization Server is brain-mcp itself (issuer = `https://brain-mcp.d-ma.be`), not Dex — `brain-mcp`'s own `/oauth/token` endpoint implements `client_credentials` per `ingestion/internal/oauth/token.go`. Client secret validated against the SOPS-stored `OAUTH_CLIENT_SECRET`; on success the same static `BRAIN_MCP_TOKEN` is returned as the bearer (so the static-Bearer code path and the OAuth code path converge on the same token, just with two arrival routes). Closes.

mathias closed this issue

2026-05-20 07:46:26 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mathias/hyperguild#21