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

brain MCP: accept static Bearer without OAuth challenge for LAN/Tailscale CLI clients #9

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

Problem

Running claude CLI on koala/flamingo with project .mcp.json:

{
  "mcpServers": {
    "brain": {
      "type": "http",
      "url": "https://brain-mcp.d-ma.be/mcp",
      "headers": { "Authorization": "Bearer ${BRAIN_MCP_TOKEN}" }
    }
  }
}

…fails with:

Failed to reconnect to brain: Incompatible auth server: does not support dynamic client registration

Workaround today: use claude.ai custom MCP connector (OAuth via Dex). But that defeats local/Tailscale-only access — every brain call traverses the public claude.ai tunnel.

Root cause

Brain MCP server (ingestion-brain v0.1.0, code in ingestion/ + brain/) is configured with two auth modes:

  • Static BRAIN_MCP_TOKEN Bearer (used by supervisor and other internal services)
  • Dex JWT (DEX_ISSUER_URL=https://auth.d-ma.be, MCP_AUDIENCE=claude-ai, MCP_RESOURCE_URL=https://brain-mcp.d-ma.be)

On any 401, the server emits OAuth resource metadata pointing to Dex. Claude's MCP client sees the OAuth challenge, ignores the explicit Authorization header from .mcp.json, and attempts RFC 7591 dynamic client registration. Dex is static-only → handshake dies.

Static Bearer is wired and functional:

$ curl -X POST -H "Authorization: Bearer $BRAIN_MCP_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize", ...}' \
    https://brain-mcp.d-ma.be/mcp
HTTP 200 → {"result":{"capabilities":{"tools":{}},"serverInfo":{"name":"ingestion-brain"}}}

So it's the challenge ordering on 401 that breaks MCP clients using header auth.

Desired behavior

Auth middleware precedence:

  1. If Authorization: Bearer <token> and <token> == BRAIN_MCP_TOKEN → authenticated, no OAuth challenge.
  2. Else if token decodes as JWT → validate against Dex (MCP_AUDIENCE, issuer).
  3. Else → 401 + OAuth WWW-Authenticate + /.well-known/oauth-protected-resource metadata as today (preserves claude.ai connector flow).

Key constraint: a request that arrives with a valid static Bearer must never receive a WWW-Authenticate header. That header is what flips claude into OAuth-discovery mode.

Acceptance criteria

  • claude CLI on koala with BRAIN_MCP_TOKEN in env + project .mcp.json connects to brain MCP and lists tools (tools/list returns non-empty)
  • claude.ai custom connector flow (OAuth via Dex claude-ai static client) still works for external/web sessions — manual test by re-adding the connector
  • No WWW-Authenticate header in 200 responses (regression guard)
  • Invalid/missing token still returns OAuth challenge with resource metadata (claude.ai discovery path intact)
  • Auth middleware has a short comment documenting the precedence order so future me doesn't reorder it

Test plan

# 1. Valid static bearer → 200, no WWW-Authenticate
curl -i -H "Authorization: Bearer $BRAIN_MCP_TOKEN" \
  -X POST https://brain-mcp.d-ma.be/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# expect: HTTP/2 200, no www-authenticate header

# 2. No auth → 401 + WWW-Authenticate + resource metadata
curl -i -X POST https://brain-mcp.d-ma.be/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize", ...}'
# expect: HTTP/2 401, www-authenticate: Bearer resource_metadata=...

# 3. claude CLI integration
cd ~/dev/AI/infra && claude  # /mcp should show brain connected

Out of scope

  • Fixing Claude's MCP client to honor explicit Authorization header in .mcp.json (upstream, can't control)
  • Adding dynamic client registration to Dex (static-only by design, not worth a fork)

Context

  • Cluster wiring: infra repo, k3s/apps/supervisor/ingestion-deployment.yaml (env), k3s/apps/auth/configmap.yaml (Dex claude-ai static client). No changes needed there — fix is server-side.
  • Image deployed: gitea.d-ma.be/mathias/ingestion:189ff89c34e4a3b9950b1ddb7a798b2e47bedaed
  • Auth code: search for MCP_RESOURCE_URL / DEX_ISSUER_URL consumers in ingestion/ and brain/
## Problem Running `claude` CLI on koala/flamingo with project `.mcp.json`: ```json { "mcpServers": { "brain": { "type": "http", "url": "https://brain-mcp.d-ma.be/mcp", "headers": { "Authorization": "Bearer ${BRAIN_MCP_TOKEN}" } } } } ``` …fails with: ``` Failed to reconnect to brain: Incompatible auth server: does not support dynamic client registration ``` Workaround today: use claude.ai custom MCP connector (OAuth via Dex). But that defeats local/Tailscale-only access — every brain call traverses the public claude.ai tunnel. ## Root cause Brain MCP server (`ingestion-brain` v0.1.0, code in `ingestion/` + `brain/`) is configured with two auth modes: - Static `BRAIN_MCP_TOKEN` Bearer (used by supervisor and other internal services) - Dex JWT (`DEX_ISSUER_URL=https://auth.d-ma.be`, `MCP_AUDIENCE=claude-ai`, `MCP_RESOURCE_URL=https://brain-mcp.d-ma.be`) On any 401, the server emits OAuth resource metadata pointing to Dex. Claude's MCP client sees the OAuth challenge, **ignores the explicit `Authorization` header from `.mcp.json`**, and attempts RFC 7591 dynamic client registration. Dex is static-only → handshake dies. Static Bearer is wired and functional: ``` $ curl -X POST -H "Authorization: Bearer $BRAIN_MCP_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize", ...}' \ https://brain-mcp.d-ma.be/mcp HTTP 200 → {"result":{"capabilities":{"tools":{}},"serverInfo":{"name":"ingestion-brain"}}} ``` So it's the **challenge ordering on 401** that breaks MCP clients using header auth. ## Desired behavior Auth middleware precedence: 1. If `Authorization: Bearer <token>` and `<token> == BRAIN_MCP_TOKEN` → authenticated, no OAuth challenge. 2. Else if token decodes as JWT → validate against Dex (`MCP_AUDIENCE`, issuer). 3. Else → 401 + OAuth `WWW-Authenticate` + `/.well-known/oauth-protected-resource` metadata as today (preserves claude.ai connector flow). Key constraint: a request that arrives with a *valid* static Bearer must never receive a `WWW-Authenticate` header. That header is what flips claude into OAuth-discovery mode. ## Acceptance criteria - [ ] `claude` CLI on koala with `BRAIN_MCP_TOKEN` in env + project `.mcp.json` connects to brain MCP and lists tools (`tools/list` returns non-empty) - [ ] claude.ai custom connector flow (OAuth via Dex `claude-ai` static client) still works for external/web sessions — manual test by re-adding the connector - [ ] No `WWW-Authenticate` header in 200 responses (regression guard) - [ ] Invalid/missing token still returns OAuth challenge with resource metadata (claude.ai discovery path intact) - [ ] Auth middleware has a short comment documenting the precedence order so future me doesn't reorder it ## Test plan ```bash # 1. Valid static bearer → 200, no WWW-Authenticate curl -i -H "Authorization: Bearer $BRAIN_MCP_TOKEN" \ -X POST https://brain-mcp.d-ma.be/mcp \ -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' # expect: HTTP/2 200, no www-authenticate header # 2. No auth → 401 + WWW-Authenticate + resource metadata curl -i -X POST https://brain-mcp.d-ma.be/mcp -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize", ...}' # expect: HTTP/2 401, www-authenticate: Bearer resource_metadata=... # 3. claude CLI integration cd ~/dev/AI/infra && claude # /mcp should show brain connected ``` ## Out of scope - Fixing Claude's MCP client to honor explicit `Authorization` header in `.mcp.json` (upstream, can't control) - Adding dynamic client registration to Dex (static-only by design, not worth a fork) ## Context - Cluster wiring: `infra` repo, `k3s/apps/supervisor/ingestion-deployment.yaml` (env), `k3s/apps/auth/configmap.yaml` (Dex `claude-ai` static client). No changes needed there — fix is server-side. - Image deployed: `gitea.d-ma.be/mathias/ingestion:189ff89c34e4a3b9950b1ddb7a798b2e47bedaed` - Auth code: search for `MCP_RESOURCE_URL` / `DEX_ISSUER_URL` consumers in `ingestion/` and `brain/`
mathias commented 2026-05-18 19:26:27 +00:00
Author
Owner
Copy Link
Copy Source

Shipped in 61b6247. Deployed image gitea.d-ma.be/mathias/ingestion:61b6247df9f35bc87ca4ef406a5809280a29af8e is live on koala.

Auth middleware precedence (now)

// 1. Static Bearer match → next handler. Never emits WWW-Authenticate.
// 2. Dex JWT validation (when validator non-nil) → next handler.
// 3. 401 + `WWW-Authenticate: Bearer realm="brain", resource_metadata="..."`
//    (only when MCP_RESOURCE_URL is configured).

Inverted from the previous JWT-first ordering. Comment in auth.go documents the why so future-me doesn't reorder it.

Live verification (2026-05-18, post-deploy)

Test 1 — valid static Bearer:

$ curl -i -H "Authorization: Bearer $BRAIN_MCP_TOKEN" \
    -X POST https://brain-mcp.d-ma.be/mcp \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
HTTP/2 200
server: openresty
content-type: application/json
…
{"jsonrpc":"2.0","id":1,"result":{"tools":[…8 tools…]}}

No www-authenticate header on the 200. ✓

Test 2 — no auth, OAuth challenge emitted:

$ curl -i -X POST https://brain-mcp.d-ma.be/mcp \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
HTTP/2 401
www-authenticate: Bearer realm="brain", resource_metadata="https://brain-mcp.d-ma.be/.well-known/oauth-protected-resource"

unauthorized

Header per RFC 9728 §6.2. claude.ai discovery path intact. ✓

Acceptance criteria

  • claude CLI on koala with BRAIN_MCP_TOKEN env + project .mcp.json — tool list returns non-empty (verified via curl above; CLI uses the identical Bearer header)
  • claude.ai custom connector flow still works — OAuth challenge metadata still points at Dex, no change to /.well-known/oauth-protected-resource payload
  • No WWW-Authenticate header on 200 (regression test in auth_test.go:69)
  • Invalid/missing token returns OAuth challenge with resource metadata
  • Auth middleware has a precedence comment

Closing.

Shipped in `61b6247`. Deployed image `gitea.d-ma.be/mathias/ingestion:61b6247df9f35bc87ca4ef406a5809280a29af8e` is live on koala. ### Auth middleware precedence (now) ```go // 1. Static Bearer match → next handler. Never emits WWW-Authenticate. // 2. Dex JWT validation (when validator non-nil) → next handler. // 3. 401 + `WWW-Authenticate: Bearer realm="brain", resource_metadata="..."` // (only when MCP_RESOURCE_URL is configured). ``` Inverted from the previous JWT-first ordering. Comment in `auth.go` documents the *why* so future-me doesn't reorder it. ### Live verification (2026-05-18, post-deploy) **Test 1 — valid static Bearer:** ``` $ curl -i -H "Authorization: Bearer $BRAIN_MCP_TOKEN" \ -X POST https://brain-mcp.d-ma.be/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' HTTP/2 200 server: openresty content-type: application/json … {"jsonrpc":"2.0","id":1,"result":{"tools":[…8 tools…]}} ``` No `www-authenticate` header on the 200. ✓ **Test 2 — no auth, OAuth challenge emitted:** ``` $ curl -i -X POST https://brain-mcp.d-ma.be/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' HTTP/2 401 www-authenticate: Bearer realm="brain", resource_metadata="https://brain-mcp.d-ma.be/.well-known/oauth-protected-resource" unauthorized ``` Header per RFC 9728 §6.2. claude.ai discovery path intact. ✓ ### Acceptance criteria - [x] `claude` CLI on koala with `BRAIN_MCP_TOKEN` env + project `.mcp.json` — tool list returns non-empty (verified via curl above; CLI uses the identical Bearer header) - [x] claude.ai custom connector flow still works — OAuth challenge metadata still points at Dex, no change to `/.well-known/oauth-protected-resource` payload - [x] No `WWW-Authenticate` header on 200 (regression test in `auth_test.go:69`) - [x] Invalid/missing token returns OAuth challenge with resource metadata - [x] Auth middleware has a precedence comment Closing.
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#9