> ## Documentation Index
> Fetch the complete documentation index at: https://docs.proofable.me/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP auth

> Host Connect for interactive MCP clients, access key fallback, and token security.

Interactive MCP clients sign in through the host. Register `https://mcp.proofable.me/mcp`, click **Connect**, and finish browser sign-in. 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 profile access key instead.

## Sign in

1. Register the hosted remote once (plugin, registry listing, or URL-only MCP config).
2. Click **Connect** in the host MCP panel.

Optional terminal installer (writes the same URL):

```bash theme={"dark"}
npx -y -p @proofable/sdk proofable setup
```

See [Connect Proofable](./setup).

OAuth-capable hosts discover Proofable metadata from the hosted MCP server:

```text theme={"dark"}
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)
```

`tools/list` and `ping` stay public so marketplaces can list tools. Unauthenticated `initialize` and every `tools/call` return `401` + `WWW-Authenticate` so the host shows **Connect**, stores the access token, and sends it on later calls. A GET probe on `/mcp` is not a login challenge.

For full OAuth mechanics, see [MCP OAuth](./oauth).

## Access key (fallback)

Use a **profile access key** from [Access Keys](https://proofable.me/profile?tab=account) when browser OAuth is not available: servers, CI, and automation.

```bash theme={"dark"}
proofable setup --access-key <npk_...>
```

## Choose an auth mode

| Mode                     | Best for                                                                                 |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| **Host Connect (OAuth)** | Interactive clients: 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

```http theme={"dark"}
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](./overview) for the reuse-first flow.

## Disconnect

```bash theme={"dark"}
proofable disconnect --access-key <token>
```

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

## MCP server auth challenge

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

```http theme={"dark"}
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"
```

Hosts that support MCP OAuth follow that metadata and open Connect. Stateless streamable HTTP has no GET SSE stream: GET and DELETE on `/mcp` return **405** with no `WWW-Authenticate`. Do not treat a GET probe as a sign-in prompt.

## Interactive verification flows

[Hosted Verify](../cookbook/auth-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](https://proofable.me/profile?tab=account) if exposed     |
| Refresh tokens    | Rotated on each use, old token invalidated                                                       |
| `hostedVerifyUrl` | Send the user to the returned Proofable hosted flow                                              |

<CardGroup cols={3}>
  <Card title="MCP OAuth" icon="shield-check" href="./oauth" />

  <Card title="Setup" icon="code" href="./setup" />

  <Card title="Hosted Verify" icon="key" href="../cookbook/auth-hosted-verify" />
</CardGroup>