NEUS Docs

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.

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:

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.

Access key (fallback)

Use a profile access key from Access Keys when browser OAuth is not available — servers, CI, and automation.

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

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 for the reuse-first flow.

Disconnect

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/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: 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 if exposed
Refresh tokens	Rotated on each use — old token invalidated
`hostedVerifyUrl`	Send the user to the returned NEUS hosted flow

Start

Tool reference

MCP Auth & Security

Access key (fallback)

Choose an auth mode

Authorization header

Disconnect

MCP server auth challenge

Interactive verification flows

Security

MCP OAuth

Setup

Hosted Verify

​OAuth sign-in

​Access key (fallback)

​Choose an auth mode

​Authorization header

​Disconnect

​MCP server auth challenge

​Interactive verification flows

​Security

MCP OAuth

Setup

Hosted Verify

OAuth sign-in

Access key (fallback)

Choose an auth mode

Authorization header

Disconnect

MCP server auth challenge

Interactive verification flows

Security