---

IDENTITY

title: "TICKET_054: Add OAuth 2.1 to Bus MCP Server for Custom Connectors"
type: ticket
subtype: execution
purpose: "Implement MCP-spec OAuth 2.1 on the Bus MCP Server so claude.ai Custom Connectors (B1-B5 web tabs) can authenticate and connect."

GOVERNANCE

status: ready
priority: P0
sprint: S001_base_and_mvp1
assignee: "CM0 (build on Mac) → CC0 (deploy on Hetzner)"
estimated_hours: 2
depends_on: [TICKET_049]
blocks: [TICKET_053]
last_updated: "2026-03-22 01:00"
blueprint: "BLUEPRINT_Bus_MCP_Server_v1.md"

TICKET_054: Add OAuth 2.1 to Bus MCP Server

Problem

Claude.ai Custom Connectors do NOT support raw bearer tokens. They only support:

1. Authless (no auth)
2. OAuth 2.0/2.1 with authorization code flow

Our Bus MCP Server currently only has bearer token auth. Web brains (B1-B5) cannot connect via Custom Connectors without OAuth.

Claude Code CLI (CM0/CC0) already works with bearer tokens via claude mcp add. This ticket adds OAuth for web surfaces only.

Solution

Implement the MCP OAuth 2.1 authorization spec on the Bus MCP Server. Claude will act as the OAuth client using our registered Client ID.

Key Facts from Research

• Claude's OAuth callback URL: https://claude.ai/api/mcp/auth_callback
• Also allowlist: https://claude.com/api/mcp/auth_callback
• Claude supports Dynamic Client Registration (DCR) — but we can also use static client ID
• Custom connectors UI: user enters URL + optional Client ID
• Pure client credentials (machine-to-machine) NOT supported — must be authorization code flow
• Claude stores encrypted access tokens + refresh tokens server-side
• Claude handles token refresh automatically

Implementation Plan

Step 1: Add OAuth discovery endpoints

GET /.well-known/oauth-authorization-server

{
  "issuer": "https://bus.struxio.ai",
  "authorization_endpoint": "https://bus.struxio.ai/oauth/authorize",
  "token_endpoint": "https://bus.struxio.ai/oauth/token",
  "registration_endpoint": "https://bus.struxio.ai/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["bus:read", "bus:write", "paperclip:read", "paperclip:write"]
}

GET /.well-known/oauth-protected-resource

{
  "resource": "https://bus.struxio.ai/mcp",
  "authorization_servers": ["https://bus.struxio.ai"]
}

Step 2: Add OAuth endpoints

POST /oauth/register — Dynamic Client Registration

• Accepts: client_name, redirect_uris, grant_types, response_types
• Returns: client_id, client_secret
• Store in new oauth_clients table

GET /oauth/authorize — Authorization endpoint

• Params: client_id, redirect_uri, response_type=code, code_challenge, code_challenge_method=S256, state, scope
• For STRUXIO: auto-approve (no user consent screen needed — all brains are trusted)
• Generate authorization code, store in DB
• Redirect to redirect_uri with code and state

POST /oauth/token — Token exchange

• Grant type authorization_code: exchange code for access_token + refresh_token
• Grant type refresh_token: issue new access_token from refresh_token
• Access tokens: JWT or opaque, short-lived (1 hour)
• Refresh tokens: long-lived (30 days)

Step 3: New database tables

CREATE TABLE oauth_clients (
  client_id TEXT PRIMARY KEY,
  client_secret_hash BYTEA NOT NULL,
  client_name TEXT NOT NULL,
  redirect_uris TEXT[] NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE oauth_codes (
  code TEXT PRIMARY KEY,
  client_id TEXT NOT NULL REFERENCES oauth_clients(client_id),
  principal_id UUID REFERENCES principals(principal_id),
  redirect_uri TEXT NOT NULL,
  code_challenge TEXT,
  code_challenge_method TEXT,
  scope TEXT,
  expires_at TIMESTAMPTZ NOT NULL,
  used_at TIMESTAMPTZ
);

CREATE TABLE oauth_tokens (
  token_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  access_token_hash BYTEA NOT NULL UNIQUE,
  refresh_token_hash BYTEA UNIQUE,
  client_id TEXT NOT NULL REFERENCES oauth_clients(client_id),
  principal_id UUID REFERENCES principals(principal_id),
  scope TEXT,
  access_expires_at TIMESTAMPTZ NOT NULL,
  refresh_expires_at TIMESTAMPTZ,
  revoked_at TIMESTAMPTZ
);

Step 4: Update auth middleware

The /mcp endpoint should accept BOTH:

• Bearer token (existing — for CLI agents CM0/CC0)
• OAuth access token (new — for web brains B1-B5 via Custom Connectors)

Auth flow:

1. Check Authorization: Bearer <token> header
2. Try bearer token lookup (existing api_tokens table)
3. If not found, try OAuth access token lookup (oauth_tokens table)
4. If neither: return 401 with WWW-Authenticate: Bearer + PRM pointer

Step 5: Auto-approve logic

Since all STRUXIO brains are trusted, the authorize endpoint should auto-approve without showing a consent screen:

• If redirect_uri matches Claude's callback (claude.ai or claude.com): auto-approve
• Generate code, redirect immediately
• Map to a default principal (create one per client_id if needed)

Step 6: Files to create/modify

New files:

• src/auth/oauth.ts — OAuth endpoints (register, authorize, token)
• src/auth/oauth_store.ts — DB queries for oauth_clients, oauth_codes, oauth_tokens
• src/store/migrations/002_oauth.sql — New tables

Modified files:

• src/server.ts — Mount OAuth routes
• src/auth/tokens.ts — Support both bearer + OAuth token validation

Step 7: Caddy update

Add OAuth routes to Caddyfile:

handle /oauth/* {
  reverse_proxy bus:8088
}
handle /.well-known/* {
  reverse_proxy bus:8088
}

Execution Workflow

1. CM0 implements the code on Mac, builds, tests locally, pushes to GitHub
2. CC0 pulls from GitHub, rebuilds container, runs migration 002, smoke tests
3. Shai adds Custom Connector in claude.ai: URL = https://bus.struxio.ai/mcp
4. Claude initiates OAuth flow → auto-approved → tools available in web chats

Acceptance Criteria

• /.well-known/oauth-authorization-server returns valid metadata
• /.well-known/oauth-protected-resource returns resource pointer
• Dynamic Client Registration works (POST /oauth/register)
• Authorization code flow completes with PKCE
• Token exchange returns access_token + refresh_token
• Refresh token grant works
• Existing bearer tokens still work (backward compatible)
• Custom Connector added in claude.ai settings successfully
• B1 web tab can call bus.poll via the connector
• Cross-brain message: B0 → B1 via bus.send_message, B1 reads via bus.poll

Rollback

Remove OAuth routes. Bearer token auth continues to work for CLI agents.

---

STRUXIO.ai // Confidential & Proprietary // © 2026