MCP auth

Interactive MCP clients sign in through the host. Register https://mcp.proofable.me/mcp — it answers an uncredentialed handshake with 401 + WWW-Authenticate, which starts the browser sign-in your client opens. The host runs OAuth 2.0 with PKCE and can refresh the session for up to 30 days. For servers, CI, and environments that cannot open a browser, use a durable server key against the same https://mcp.proofable.me/mcp endpoint. Both paths reach the same Proofable profile and the same OAuth resource audience.

Register the hosted remote once (plugin, registry listing, or URL-only MCP config).
Start the sign-in in the client’s MCP panel.

Optional terminal installer (writes the same URL):

npx -y @proofable/sdk setup

See Add Proofable to any MCP client. OAuth-capable hosts discover Proofable metadata from the hosted MCP server:

GET https://mcp.proofable.me/.well-known/mcp.json
  → authorization.resource_metadata_url
GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-protected-resource/mcp
GET https://proofable.me/.well-known/oauth-authorization-server
→ /oauth/authorize (HostedLoginFlow)
→ Token exchange
→ Authenticated MCP session (Bearer on protected MCP requests)

https://mcp.proofable.me/mcp is the single canonical endpoint. Any request without a usable credential — including initialize — returns 401 + WWW-Authenticate (RFC 9728 §5.1), which is the challenge that starts host OAuth (DCR + PKCE + token exchange). A valid Bearer unlocks the full advertised tier, and tools/call runs the applicable tool surface. Access keys and OAuth use the same URL. An expired or invalid Bearer also receives 401 + WWW-Authenticate once, so OAuth-capable hosts silently refresh. For full OAuth mechanics, see MCP OAuth.

Access key (servers and automation)

Use a server key from Access Keys when browser OAuth is not available: servers, CI, cron, containers, cloud agents, and gateways. Set the canonical environment variable and let the CLI write the config:

export PROOFABLE_ACCESS_KEY=npk_...
proofable setup --access-key $PROOFABLE_ACCESS_KEY

Or paste the block into any client’s MCP settings:

{
  "mcpServers": {
    "proofable": {
      "type": "http",
      "url": "https://mcp.proofable.me/mcp",
      "headers": {
        "Authorization": "Bearer ${PROOFABLE_ACCESS_KEY}"
      }
    }
  }
}

Marketplace gateways that reserve Authorization for their own OAuth (such as Smithery) forward the same key as x-proofable-access-key; the hosted MCP maps it onto the same Bearer principal. That is a transport alias, not a second credential: same npk_* key, same profile, same revocation path. Leave the gateway’s key field empty to use the host’s own sign-in instead.

Choose an auth mode

Mode	Best for
Host sign-in (OAuth)	Interactive clients: the host opens browser sign-in, no manual keys, silent refresh for 30 days
*Access key (`npk_`)**	Servers, CI, and automation with stable environment variables. Durable and never expires

Both modes send the same Authorization: Bearer <token> header against the same Proofable Profile and Account. npk_* keys are long-lived credentials. OAuth sessions are long-lived too. The host refreshes the short-lived access token silently for up to 30 days via the offline_access refresh token. Anonymous proof checking and verifier catalog reads stay available through the web UI and the HTTP API.

Authorization header

Authorization: Bearer <token>

OAuth tokens and access keys both use the Bearer scheme. Authenticated MCP sessions should reuse existing proofs before any browser step. See MCP Overview for the reuse-first flow.

Disconnect

proofable disconnect --access-key <token>

Disconnect revokes OAuth MCP tokens through the OAuth revocation endpoint. For npk_* credentials, it revokes the server key through the Proofable API, then removes the local MCP header from configured clients.

MCP server auth challenge

When a client calls a protected operation without credentials, the server returns:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.proofable.me/mcp/.well-known/oauth-protected-resource", scope="neus:core neus:profile neus:secrets"

Any request without a credential — including initialize — returns the 401 + WWW-Authenticate challenge on /mcp, which is what hosts act on to open Connect. Stateless streamable HTTP has no GET SSE stream: GET and DELETE on /mcp return 405 with no WWW-Authenticate, so a GET probe is not a sign-in prompt.

Interactive verification flows

Hosted Verify: passkey, wallet, OAuth, and social verification steps run on Proofable. If a tool returns hostedVerifyUrl, open it once, then continue in MCP.

Security

Topic	Rule
OAuth tokens	Stored by the MCP host, never in query strings
Access keys	Server or automation configuration only. Never in interactive host `mcp.json` when Connect works
Browser exposure	Never expose tokens or access keys in browser code
Rotation	Re-issue access keys from Access Keys if exposed
Refresh tokens	Rotated on each use, old token invalidated
`hostedVerifyUrl`	Send the user to the returned Proofable hosted flow

Overview

MCP

JavaScript SDK

HTTP API

Verifier catalog

Standards

Access key (servers and automation)

Choose an auth mode

Authorization header

Disconnect

MCP server auth challenge

Interactive verification flows

Security

MCP OAuth

Setup

Hosted Verify

​Sign in

​Access key (servers and automation)

​Choose an auth mode

​Authorization header

​Disconnect

​MCP server auth challenge

​Interactive verification flows

​Security

MCP OAuth

Setup

Hosted Verify

Sign in

Access key (servers and automation)

Choose an auth mode

Authorization header

Disconnect

MCP server auth challenge

Interactive verification flows

Security