The MCP Surface

One endpoint, streamable HTTP transport. The /mcp suffix is canonical; it is the OAuth resource indicator clients register against.

A client that follows RFC 9728 finds everything it needs from a single 401. Fail, read the metadata, register, run PKCE.

# 1. Fail and discover
curl -i -X POST https://mcp.dev.arch.ie/mcp \
  -H 'content-type: application/json' -d '{}'
# → 401 Unauthorized
# → www-authenticate: Bearer resource_metadata="https://mcp.dev.arch.ie/.well-known/oauth-protected-resource"

# 2. Protected-resource metadata (RFC 9728)
curl -s https://mcp.dev.arch.ie/.well-known/oauth-protected-resource

# 3. Authorization-server metadata (RFC 8414)
curl -s https://mcp.dev.arch.ie/.well-known/oauth-authorization-server

# 4. Dynamic client registration (RFC 7591, no pre-shared client_id)
curl -s -X POST https://mcp.dev.arch.ie/oauth/register \
  -H 'content-type: application/json' \
  -d '{"redirect_uris":["https://your-client.example/callback"],"client_name":"My MCP client"}'

Standard OAuth 2.1 authorization code with PKCE. WorkOS AuthKit is the identity provider; Archie owns the issuer and the scope layer. Token endpoint auth method is none, a public client, PKCE only. The full walkthrough with the sequence diagram lives on the authentication page.

1. 1
   Call without a token

   A client POSTs to the MCP endpoint with no bearer. Archie returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata.

2. 2
   Read protected-resource metadata

   /.well-known/oauth-protected-resource (RFC 9728) names the authorization server. The resource value is Host-derived, so the same code path serves every tier.

3. 3
   Read authorization-server metadata

   /.well-known/oauth-authorization-server (RFC 8414) gives the authorize, token, and registration endpoints.

4. 4
   Register dynamically

   POST /oauth/register (RFC 7591) returns an archie_mcp_* client id. No pre-shared secret: public client, PKCE only.

5. 5
   Run PKCE consent

   GET /oauth/authorize with code_challenge redirects to WorkOS AuthKit. The user signs in with the firm's SSO and picks a workspace.

6. 6
   Exchange the code for a token

   POST /oauth/token with the code and code_verifier returns the access token. Every MCP call after that carries it.

An HS256 JWT signed with the issuer's secret. The iss claim has to match the tier's connector URL or the call is rejected at the bearer-resolver layer.

{
  "iss": "https://claude.dev.arch.ie",
  "sub": "user_01ABC...",
  "org_id": "org_01XYZ...",
  "workspace_id": "ws_01...",
  "scope": "read:accounting read:clients write:journals",
  "exp": 1734567890,
  "token_type": "archie_oauth"
}

The iss and resource values are Host-header-derived. One code path serves every tier; only the deploy environment's base URL changes.

Archie negotiates the protocol version on connect. Two are current; clients send loopback redirect URIs (http://127.0.0.1:*) for local dev in the spirit of OAuth 2.1 §10.3.3.

Anything weird in the spec? Email [email protected]. To add a client, start at Connect Claude; to see what Archie carries, the tool catalog.