MCP Scoped API Keys

Per-key MCP scopes with proper JSON-RPC insufficient_scope errors — opt-in, backward compatible

Give different MCP clients different API keys, each with different powers — reader can list tools, agent-bot can call them, admin can do everything.

Quick Start

1. Create a keys file

   Give each client a key and a list of scopes. * means “all scopes”.

   {
     "keys": [
       { "key": "reader-abc", "scopes": ["tools:read", "resources:read"] },
       { "key": "agent-def",  "scopes": ["tools:call", "tools:read"] },
       { "key": "admin-ghi",  "scopes": ["*"] }
     ]
   }

2. Serve with the keys file

   praisonai mcp serve --transport http-stream --port 8080 --keys-file ./keys.json

   Each request sends its key as a Bearer token. The server looks up the key, resolves its scopes, and enforces them per method.

3. Single key (unchanged)

   A single scalar key still works and gets wildcard (*) scope — every method allowed.

   praisonai mcp serve --transport http-stream --api-key MY_SECRET

How It Works

Each method has a required scope. The transport resolves the caller’s key to granted_scopes and the server checks it before running the handler.

Two Ways to Configure

Pick the shortest path for your setup.

A) Single key (wildcard)

praisonai mcp serve --transport http-stream --api-key MY_SECRET

Behaviour is unchanged. The scalar --api-key is wrapped as a single key with wildcard (*) scope, so it satisfies every method — the scalar path and the multi-key path share the same enforcement.

B) Multiple scoped keys

praisonai mcp serve --transport http-stream --keys-file ./keys.json

{
  "keys": [
    { "key": "reader-abc", "scopes": ["tools:read", "resources:read"] },
    { "key": "agent-def",  "scopes": ["tools:call", "tools:read"] },
    { "key": "admin-ghi",  "scopes": ["*"] }
  ]
}

Scopes and Methods

Each MCP method maps to a required scope in OPERATION_SCOPES.

Runtime log-level changes are administrative, so logging/setLevel sits behind the admin scope — a client cannot quiet or verbose the server’s logging without an admin key.

Available scopes:

Error Response

A request without the required scope returns a JSON-RPC error with code -32001.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "insufficient_scope",
    "data": { "required": "tools:call" }
  }
}

Over HTTP the response also carries a challenge header naming the missing scope:

WWW-Authenticate: Bearer realm="mcp", scope="tools:call", error="insufficient_scope"

The client can read scope="…" to know exactly which grant to request next.

Common Patterns

Match a key’s scopes to what each client actually needs.

{ "key": "monitor-key", "scopes": ["tools:read", "resources:read"] }

{ "key": "agent-key", "scopes": ["tools:call"] }

{ "key": "admin-key", "scopes": ["*"] }

{
  "keys": [
    { "key": "agent-old", "scopes": ["tools:call"] },
    { "key": "agent-new", "scopes": ["tools:call"] }
  ]
}

Best Practices

Related