@apoa/mcp

APOA authorization for MCP servers. Per-tool-call scoping, delegation chains, audit trails.

MCP has OAuth 2.1 for connection-level auth (who can connect). This package adds action-level auth (what they can do once connected).

MCP Client --> @apoa/mcp --> MCP Server
               (authorize every tool call)

Two Modes

Middleware (for servers you build)

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { withAPOA } from '@apoa/mcp';

const server = new Server({ name: 'my-server', version: '1.0.0' }, { capabilities: { tools: {} } });

withAPOA(server, {
  key: publicKey,
  mappings: {
    read_file:  'filesystem:files:read',
    write_file: 'filesystem:files:write',
    list_dir:   'filesystem:dirs:list',
  },
});

Three lines. Every tool call is authorized against an APOA token passed in _meta.apoa_token. No token, no access.

Proxy (for third-party servers you can't modify)

npx apoa-mcp --config gateway.config.json

Sits between client and server, intercepts every tools/call, authorizes, strips the token, forwards.

How It Works

1. MCP client passes an APOA token in _meta.apoa_token on every tool call
2. The tool name is mapped to an APOA service:scope pair
3. The token is verified (signature, expiration, revocation, replay)
4. The SDK's authorize() checks scope, constraints, and rules
5. If authorized, the tool runs. If not, the client gets a denial with a reason.

The token is stripped before reaching the tool handler -- the tool never sees it.

Passing Tokens

MCP clients include an APOA token in the _meta field on each tool call:

import { APOA, generateKeyPair } from '@apoa/core';

const keys = await generateKeyPair();
const apoa = new APOA({ privateKey: keys.privateKey });

const grant = await apoa.tokens.createGrant({
  principal: 'did:apoa:alice',
  agent: 'did:apoa:research-agent',
  service: 'filesystem',
  scopes: ['files:read'],
  expiresIn: '1h',
});

Pass grant.raw as _meta.apoa_token:

{
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/tmp/test.txt",
      "_meta": {
        "apoa_token": "<grant.raw>"
      }
    }
  }
}

On the MCP server side, configure withAPOA() with the matching public key:

withAPOA(server, {
  key: keys.publicKey,
  mappings: {
    read_file: 'filesystem:files:read',
  },
});

Tool Mappings

Simple format (one string per tool):

withAPOA(server, {
  key: publicKey,
  mappings: {
    read_file:  'filesystem:files:read',
    write_file: 'filesystem:files:write',
  },
});

Auto-mapping (no config needed):

withAPOA(server, { key: publicKey });
// read_file -> read_file:call, write_file -> write_file:call, etc.

Conditional mappings (argument-aware):

{
  "toolMappings": [
    { "tool": "write_file", "service": "filesystem", "scope": "files:write:sandbox",
      "when": { "path": { "startsWith": "/tmp" } }, "priority": 10 },
    { "tool": "write_file", "service": "filesystem", "scope": "files:write" }
  ]
}

apoa.check (Dry-Run Tool)

Enable it to inject a debugging tool that checks authorization without executing:

withAPOA(server, { key: publicKey, enableCheckTool: true });

Agents or humans can call apoa.check({ tool: 'write_file', path: '/home/data' }) to see whether the action would be authorized, what scope it maps to, and which rule would fire.

What This Adds to MCP

Capability	MCP Native	@apoa/mcp
Connection-level auth (OAuth 2.1)	Yes	N/A (complementary)
Per-tool-call authorization	No (SEP-1880 closed as NOT_PLANNED)	Yes
Delegation chains with attenuation	No	Yes (via @apoa/core)
Hard/soft rules engine	No	Yes
Constraint checking per action	No	Yes
Cascade revocation	No	Yes
Audit trail	No (roadmap "pre-RFC")	Yes (hash-chained, tamper-evident)
Replay protection	No	Yes (JTI-based)

Persistent Stores

For production, use SQLite stores instead of the default in-memory stores:

import { SqliteRevocationStore, SqliteAuditStore, SqliteReplayStore } from '@apoa/mcp';

withAPOA(server, {
  key: publicKey,
  revocationStore: new SqliteRevocationStore('./auth.db'),
  auditStore: new SqliteAuditStore('./auth.db'),
  replayStore: new SqliteReplayStore('./auth.db'),
});

The audit store uses SHA-256 hash chaining for tamper evidence.

Development

pnpm install
pnpm test          # Run tests
pnpm run typecheck # Type check
pnpm run build     # Build

License

Apache-2.0

Part of the APOA Standard

• APOA Spec
• @apoa/core (TypeScript SDK)
• apoa (Python SDK)