mathias/hyperguild
1
0
Fork 0
Code Issues 30 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-05-19 11:11:04 +00:00 by mathias · 1 comment
mathias commented 2026-05-19 11:11:04 +00:00
Owner
Copy Link
Copy Source

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: 
    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
## 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
Author
Owner
Copy Link
Copy Source

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.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agent/ready
Meets the agent-ready contract; authorizes unattended execution
 blocked/client
Waiting on the client
 blocked/supplier
Waiting on a supplier
 blocked/upstream
Waiting on an upstream project or vendor
 risk/high
Irreversible, security-relevant, or control plane
 risk/low
Reversible, local, test-covered
 risk/medium
Touches shared state, deploys or data
 size/l
Too big - split it
 size/m
Under two days
 size/s
Under half a day
 size/xs
Under an hour
 status:dispatch
status:dispatched
status:review
status:reviewing
type/chore
Maintenance, no behaviour change
 type/decision
Human decision required; never agent/ready
 type/docs
Documentation only
 type/feat
New capability
 type/fix
Corrects broken behaviour
 type/ops
Infrastructure, deploy, runtime
 type/research
Investigate; output is a finding, not code
 type/test
Test coverage only
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
renovate-bot mathias
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mathias/hyperguild#21