MCP Scoped API Keys

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

No auth configured? Nothing changes. With no keys set, granted_scopes is None and every method is allowed. Scoped keys are 100% opt-in — existing setups keep working untouched.

Quick Start

Create a keys file

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

keys.json

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

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.

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.

Step	What happens
Lookup	Transport matches the Bearer key to an `APIKeyAuth` entry
Resolve	The key’s `scopes` become `granted_scopes`
Check	The method’s required scope is compared against `granted_scopes`
Allow / Deny	Match → run handler; miss → `-32001 insufficient_scope`

When no key store is configured, granted_scopes is None and the check is skipped — allow all.

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.json

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

Field	Type	Description
`key`	`string`	The Bearer token the client sends
`scopes`	`string[]`	Scopes this key grants. `"*"` satisfies every requirement

Scopes and Methods

Each MCP method maps to a required scope in OPERATION_SCOPES.

Method	Required scope
`tools/list`	`tools:read`
`tools/call`	`tools:call`
`resources/list`	`resources:read`
`resources/read`	`resources:read`
`resources/subscribe`	`resources:subscribe`
`prompts/list`	`prompts:read`
`prompts/get`	`prompts:read`
`sampling/createMessage`	`sampling:create`
`tasks/create`	`tasks:write`
`tasks/get`	`tasks:read`
`tasks/list`	`tasks:read`
`tasks/cancel`	`tasks:write`

Available scopes:

Scope	Grants
`tools:read`	Read tool definitions
`tools:call`	Execute tools
`resources:read`	Read resources
`resources:subscribe`	Subscribe to resource changes
`prompts:read`	Read prompts
`prompts:execute`	Execute prompts
`sampling:create`	Create sampling requests
`tasks:read`	Read tasks
`tasks:write`	Create and manage tasks
`admin`	Administrative access (implies all)
`*`	Wildcard — satisfies every requirement

Scopes are hierarchical: tools:call implies tools:read, resources:subscribe implies resources:read, tasks:write implies tasks:read, and admin implies everything.

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.

Read-only monitor
Agent caller
Admin
Rotate a key

A monitoring bot that only lists tools and reads status — no execution.

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

An agent that runs tools but should not touch resources.

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

tools:call implies tools:read, so listing tools works too.

A maintenance key with full access.

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

Rotation is a pure JSON edit — add the new key, drain traffic to it, then remove the old one.

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

Best Practices

Grant the narrowest scopes that work

Start from tools:read and add only what a client needs. Reserve * and admin for maintenance keys, not day-to-day clients.

One key per client role

Give each bot or service its own key so you can rotate or revoke it without affecting others. Name keys by role (reader, agent-bot, admin).

Rotate without downtime

Add the replacement key alongside the old one, point clients at the new key, then delete the old entry. No restart of clients is forced mid-rotation.

Keep the keys file out of version control

Treat keys.json like any secret — store it outside the repo and restrict file permissions. Never commit real keys.

PraisonAI MCP Server

Run PraisonAI as an MCP server over STDIO or HTTP Stream.

MCP Authentication

API key and OAuth options for securing MCP.

MCP Client Protocol

MCP YAML Configuration

​Quick Start

​How It Works

​Two Ways to Configure

​A) Single key (wildcard)

​B) Multiple scoped keys

​Scopes and Methods

​Error Response

​Common Patterns

​Best Practices

​Related

PraisonAI MCP Server

MCP Authentication

Quick Start

How It Works

Two Ways to Configure

A) Single key (wildcard)

B) Multiple scoped keys

Scopes and Methods

Error Response

Common Patterns

Best Practices

Related