MCP + OAuth (Experimental)

§ MCP · Experimental

Official OAuth-protected MCP

The Nuvouch MCP is the hosted path for OAuth-capable agent clients. The client registers with Nuvouch, completes authorization with PKCE, pairs a hosted runtime through the user's trusted mobile device, then calls /mcp with an OAuth bearer token.

§ MCP · Discovery

Discover OAuth and MCP metadata

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

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

GET/mcp

discovery.sh

curl

curl "https://api.nuvouch.com/.well-known/oauth-authorization-server"
curl "https://api.nuvouch.com/.well-known/oauth-protected-resource/mcp"
curl "https://api.nuvouch.com/mcp"

Field	Type	Description
authorization_endpoint	url	OAuth authorization endpoint. Currently /oauth/authorize.
token_endpoint	url	OAuth token endpoint. Currently /oauth/token.
registration_endpoint	url	Dynamic client registration endpoint. Currently /oauth/register.
resource	url	Protected MCP resource URL. Currently /mcp.
scopes_supported	array	Controlled-beta scopes include identity and delegation.

§ MCP · Registration

Register an OAuth client

POST/oauth/register

dynamic registration

curl -X POST "https://api.nuvouch.com/oauth/register" \
  -H "content-type: application/json" \
  -d '{
    "client_name": "Acme Agent Client",
    "redirect_uris": [
      "https://agent.example.com/oauth/callback",
      "http://localhost:8787/oauth/callback"
    ],
    "provider_id": "generic",
    "scope": "identity delegation",
    "token_endpoint_auth_method": "none"
  }'

§ MCP · Authorization

Authorize with PKCE and mobile pairing

GET/oauth/authorize

Start an authorization-code flow with code_challenge_method=S256. If the user is already signed in and explicitly session-authorizes, Nuvouch can bind the OAuth client to an existing runtime connection. Otherwise the authorization page renders a hosted MCP pairing QR.

authorize-url.txt

example

https://api.nuvouch.com/oauth/authorize?response_type=code
  &client_id=nvr_client_123
  &redirect_uri=https%3A%2F%2Fagent.example.com%2Foauth%2Fcallback
  &scope=identity%20delegation
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.nuvouch.com%2Fmcp
  &state=opaque_state

Nuvouch creates a hosted MCP runtime pairing session.
The user scans the QR in Nuvouch mobile and receives a pairing code.
The user enters that code on the authorization page.
Nuvouch claims the runtime connection and redirects with an authorization code.

§ MCP · Tokens

Exchange, refresh, and revoke tokens

POST/oauth/token

exchange-token.sh

authorization_code

curl -X POST "https://api.nuvouch.com/oauth/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=nvr_client_123" \
  --data-urlencode "redirect_uri=https://agent.example.com/oauth/callback" \
  --data-urlencode "code=nvr_code_123" \
  --data-urlencode "code_verifier=ORIGINAL_PKCE_VERIFIER"

refresh-token.sh

refresh_token

curl -X POST "https://api.nuvouch.com/oauth/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=nvr_client_123" \
  --data-urlencode "refresh_token=nvr_refresh_123"

POST/oauth/revoke

revoke-token.sh

curl -X POST "https://api.nuvouch.com/oauth/revoke" \
  -H "content-type: application/json" \
  -d '{ "token": "nvr_access_or_refresh_token", "client_id": "nvr_client_123" }'

§ MCP · Copy-paste

Run a complete MCP OAuth flow

A production client should generate PKCE values in code. For a local smoke test, this shell outline shows the complete sequence from metadata discovery through a bearer-authenticated MCP tool call.

mcp-flow.sh

local outline

# 1. Discover metadata.
curl "https://api.nuvouch.com/.well-known/oauth-authorization-server"
curl "https://api.nuvouch.com/.well-known/oauth-protected-resource/mcp"

# 2. Register a public OAuth client.
curl -X POST "https://api.nuvouch.com/oauth/register" \
  -H "content-type: application/json" \
  -d '{
    "client_name": "Local MCP Client",
    "redirect_uris": ["http://localhost:8787/oauth/callback"],
    "provider_id": "generic",
    "scope": "identity delegation",
    "token_endpoint_auth_method": "none"
  }'

# 3. Generate a PKCE verifier and S256 challenge in your client.
export CLIENT_ID="nvr_client_123"
export REDIRECT_URI="http://localhost:8787/oauth/callback"
export CODE_VERIFIER="your-random-verifier"
export CODE_CHALLENGE="base64url-sha256-code-verifier"

# 4. Open this URL, pair with Nuvouch mobile, then capture ?code=...
open "https://api.nuvouch.com/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=http%3A%2F%2Flocalhost%3A8787%2Foauth%2Fcallback&scope=identity%20delegation&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256&resource=https%3A%2F%2Fapi.nuvouch.com%2Fmcp&state=local-test"

# 5. Exchange the code for tokens.
curl -X POST "https://api.nuvouch.com/oauth/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "redirect_uri=$REDIRECT_URI" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "code_verifier=$CODE_VERIFIER"

# 6. Call identity_get through MCP.
curl -X POST "https://api.nuvouch.com/mcp" \
  -H "Authorization: Bearer $NUVOUCH_MCP_ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"identity_get","arguments":{}}}'

delegation-request.sh

provider handoff

curl -X POST "https://api.nuvouch.com/mcp" \
  -H "Authorization: Bearer $NUVOUCH_MCP_ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "delegation_request",
      "arguments": {
        "audienceId": "aud_test_payments",
        "purpose": "Prepare a payment approval for the user.",
        "scopes": ["payments.identity", "payments.prepare"],
        "waitForApproval": true
      }
    }
  }'

# Pass the approved delegation token to the provider MCP:
curl -X POST "https://provider.example.com/mcp" \
  -H "Authorization: Bearer $PROVIDER_ACCESS_TOKEN" \
  -H "x-nuvouch-delegation: $NUVOUCH_DELEGATION_TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"payment_prepare","arguments":{"amount":84,"currency":"USD"}}}'

§ MCP · Tools

Call identity and delegation tools

POST/mcp

Every protected MCP request must include Authorization: Bearer <access_token>.

tools-list.sh

JSON-RPC over HTTP

curl -X POST "https://api.nuvouch.com/mcp" \
  -H "Authorization: Bearer $NUVOUCH_MCP_ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Field	Type	Description
identity_get	tool	Returns pairwise Nuvouch identity for the authenticated OAuth runtime.
delegation_request	tool	Creates a scoped delegation request and waits for approval by default.
delegation_status	tool	Checks or waits for an existing delegation and returns a token when approved.
delegation_revoke	tool	Revokes an active or pending delegation for the OAuth runtime.

Read identity

identity-get.sh

tools/call

curl -X POST "https://api.nuvouch.com/mcp" \
  -H "Authorization: Bearer $NUVOUCH_MCP_ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "identity_get",
      "arguments": {}
    }
  }'

Request delegation

delegation-request.sh

tools/call

curl -X POST "https://api.nuvouch.com/mcp" \
  -H "Authorization: Bearer $NUVOUCH_MCP_ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "delegation_request",
      "arguments": {
        "audienceId": "aud_test_payments",
        "purpose": "Identify the user before preparing a payment approval.",
        "scopes": ["payments.identity", "payments.prepare"],
        "waitForApproval": true
      }
    }
  }'

§ MCP · Local dev

Practical OAuth edge cases

Local redirect URIs may use http://localhost or http://127.0.0.1. Production redirect URIs should use HTTPS.
Include resource=https://api.nuvouch.com/mcp in authorization requests when your client supports OAuth protected resource indicators. It makes the intended token audience explicit.
If approval redirects to localhost and the browser shows a connection error, the OAuth decision may still be complete. Copy the code query parameter from the address bar, or start your local callback listener before retrying.
Access tokens are short-lived. Store refresh tokens server-side or in the agent client's secure credential store, and refresh before retrying MCP calls after a 401.
Non-browser clients should send normal OAuth and MCP HTTP headers. If an edge proxy challenges unusual user agents, retry with a clear product User-Agent and standard Accept headers.