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

# MCP Auth & Security

> OAuth 2.0 with PKCE for MCP clients, access key fallback, and token security.

Sign in once, then let your IDE handle the rest. NEUS MCP uses **OAuth 2.0 with PKCE** by default, so Cursor, Claude Code, VS Code, and Codex can authenticate through a browser flow and refresh your session silently for up to 30 days.

For servers, CI, and other environments that cannot open a browser, use a durable profile access key instead.

## OAuth sign-in

```bash theme={"dark"}
neus auth
```

The CLI opens your browser to the NEUS hosted sign-in page. After you authenticate with a passkey or wallet, the CLI receives an MCP access token through the standard OAuth code exchange.

OAuth-capable clients discover NEUS metadata automatically from the hosted MCP server:

```text theme={"dark"}
GET https://mcp.neus.network/.well-known/mcp.json
  → authorization.resource_metadata_url
GET /.well-known/oauth-protected-resource
GET https://neus.network/.well-known/oauth-authorization-server
→ /oauth/authorize (HostedLoginFlow)
→ Token exchange
→ Authenticated MCP session (Bearer on MCP requests)
```

When a protected resource returns `401` + `WWW-Authenticate`, OAuth-capable clients follow that metadata to sign you in and refresh tokens. Anonymous proof checking is still available through the web UI and the HTTP API.

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

## Access key (fallback)

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

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

## Choose an auth mode

| Mode                     | Best for                                                                                           |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| **OAuth**                | Cursor, VS Code, Claude Code, OpenAI — 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 NEUS Profile and Account. `npk_*` keys are long-lived credentials; OAuth sessions are long-lived too — the IDE refreshes the short-lived access token silently for up to 30 days via the `offline_access` refresh token, exactly like Linear, GitHub, and Notion MCP hosts.

Hosted MCP requires authentication on every request. Anonymous proof checking and verifier catalog reads are 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 trust receipts before any browser step. See [MCP Overview](./overview) for the reuse-first flow.

## Disconnect

```bash theme={"dark"}
neus 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 NEUS API, then removes the local MCP header from configured clients.

## MCP server auth challenge

When a client requests a protected resource without credentials, some hosts return:

```http theme={"dark"}
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.neus.network/.well-known/oauth-protected-resource"
```

Clients that support MCP OAuth follow that metadata to start browser sign-in. You can also connect with URL-only config and sign in through your host, or run **`neus auth`** from the CLI.

## Interactive verification flows

[Hosted Verify](../cookbook/auth-hosted-verify): passkey, wallet, OAuth, and social verification steps run **on NEUS**. If a tool returns **`hostedVerifyUrl`**, open it once, then continue in MCP.

## Security

| Topic             | Rule                                                                                         |
| ----------------- | -------------------------------------------------------------------------------------------- |
| OAuth tokens      | Stored by MCP client — never in query strings                                                |
| Access keys       | Server or IDE MCP configuration only                                                         |
| Browser exposure  | Never expose tokens or access keys in browser code                                           |
| Rotation          | Re-issue access keys from [Access Keys](https://neus.network/profile?tab=account) if exposed |
| Refresh tokens    | Rotated on each use — old token invalidated                                                  |
| `hostedVerifyUrl` | Send the user to the returned NEUS 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>