NEUS MCP uses OAuth 2.0 Authorization Code with PKCE as the primary authentication flow. MCP clients that support OAuth (Claude Code, OpenAI, VS Code, Cursor) authenticate through a standard browser-based flow. Access keys are the fallback for servers and automation.
OAuth
npx -y -p @neus/sdk neus auth
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)
401 + WWW-Authenticate challenge when a protected resource requires auth. Hosted NEUS MCP is open for public tools; sign in when you need account-aware context, private reads, or encrypted secrets.
Full OAuth reference: MCP OAuth.
Access key (fallback)
Use a personal access key from Access Keys when browser OAuth is not available — servers, CI, and automation.
npx -y -p @neus/sdk neus setup --access-key <npk_...>
Summary
| Mode | Use it for |
|---|
| No authentication | neus_context, neus_proofs_check, public neus_proofs_get, and verifier catalog reads |
| OAuth | Cursor, VS Code, Claude Code, OpenAI — browser sign-in, no manual keys |
Bearer (npk_* or OAuth JWT) | Same header shape — profile context in neus_context, private reads, secrets tools |
Authorization: Bearer <token>
Bearer scheme.
Authenticated MCP sessions should reuse existing trust receipts before any browser step. See MCP Overview for the reuse-first flow.
Disconnect
npx -y -p @neus/sdk neus disconnect --access-key <token>
npk_* credentials, it revokes the Profile access key through the protocol 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"
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 |
Last modified on June 8, 2026
