How MCP Authentication Works

When your MCP client connects to BlueNexus, authentication happens automatically through the MCP protocol's built-in OAuth support. This page explains the flow.

The Flow

Your MCP Client BlueNexus

POST /mcp (no token) →

← 401 + WWW-Authenticate header

GET /.well-known/oauth-protected-resource →

← { authorization_servers: [...] }

GET /.well-known/oauth-authorization-server →

← { endpoints... }

POST /v1/auth/register (DCR) →

← { client_id }

Redirect user to authorize (PKCE) →

User sees consent screen and clicks "Authorize"

← Callback with ?code=xxx

POST /v1/auth/token (code + verifier) →

← { access_token, refresh_token }

POST /mcp (Bearer token) →

← MCP response

Step-by-Step

Initial Request — Get the 401

Your client sends a request to the MCP endpoint without a token:

POST /mcp HTTP/1.1
Host: api.bluenexus.ai
Content-Type: application/json

{"jsonrpc":"2.0","method":"initialize","params":{},"id":"1"}

BlueNexus responds with 401 Unauthorized and a WWW-Authenticate header pointing to the resource metadata.

Discover the Auth Server

Your client fetches the protected resource metadata, then the authorization server metadata to discover endpoints (registration, authorization, token).

Register Your Client (DCR)

Your client auto-registers using Dynamic Client Registration (RFC 7591):

POST /api/v1/auth/register HTTP/1.1
Host: api.bluenexus.ai
Content-Type: application/json

{
  "client_name": "My AI App",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "universal-mcp-read-write"
}

Rate limited to 5 requests/minute per IP. All DCR clients receive the THIRD_PARTY role.

Authorize the User (PKCE)

Your client builds the authorization URL with a PKCE code challenge and redirects the user. The user sees a consent screen showing your app name, requested scopes, and available services.

Exchange Code for Tokens

POST /api/v1/auth/token HTTP/1.1
Host: api.bluenexus.ai
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://myapp.com/callback&
client_id=CLIENT_ID&
code_verifier=PKCE_VERIFIER

Response includes access_token (expires ~15 min), refresh_token (single-use), and scopes.

Use the MCP Endpoint

Your client makes authenticated MCP requests with the Bearer token.

POST /mcp HTTP/1.1
Host: api.bluenexus.ai
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{"jsonrpc":"2.0","method":"tools/call","params":{"name":"use-agent","arguments":{"prompt":"What's on my calendar?"}},"id":"1"}

Scopes

Scope	Access
`universal-mcp-read`	Discover tools (`tools/list`) but cannot execute
`universal-mcp-read-write`	Full access — discover and execute tools

Token Refresh

Access tokens expire after ~15 minutes. Refresh tokens are single-use — each exchange returns a new one.

POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=CLIENT_ID

Most MCP clients handle this automatically. If you're using Claude Desktop, ChatGPT, or an SDK like @modelcontextprotocol/sdk, the entire flow above is handled for you. You just configure the endpoint URL.