FastMCP Adapter

FastMCP adapters expose small verifier APIs that delegate to the verify packages. Use them when your FastMCP integration needs to authenticate a bearer token before running a tool.

They verify one token and return a small principal projection; they do not install server lifecycle hooks, create Sessions, or mint outbound mandates.

Install

Ecosystem	Package
TypeScript	npm install @caracalai/fastmcp @caracalai/verify @caracalai/revocation
Python	pip install caracalai-fastmcp

Verify a Token

TypeScript

import { extractBearer, verifyFastMcpToken } from '@caracalai/fastmcp'
import { createMandateVerifier } from '@caracalai/verify'
import { InMemoryRevocationStore } from '@caracalai/revocation'

const verifier = createMandateVerifier({
  issuer: 'https://sts.pipernet.example',
  audience: 'resource://pipernet',
  zoneId: '0195f2a9-1b22-7c3d-9e4f-5a6b7c8d9e0f',
  revocations: new InMemoryRevocationStore(),
})

const token = extractBearer(request.headers.get('authorization') ?? '')
if (!token) throw new Error('missing bearer token')

const context = await verifyFastMcpToken(token, verifier, {
  requiredScopes: ['mcp:tool:call'],
  requiredTargets: ['resource://pipernet'],
  requireSession: true,
})

console.log(context.sub, context.zoneId, context.scope)

verifyFastMcpToken() returns { sub, zoneId, scope } or throws FastMcpAuthError. The public entries are verifyFastMcpToken, extractBearer, and FastMcpAuthError.

Python

from caracalai_fastmcp import CaracalAuth, CaracalAuthError

auth = CaracalAuth(
    issuer="https://sts.pipernet.example",
    audience="resource://pipernet",
    zone_id="0195f2a9-1b22-7c3d-9e4f-5a6b7c8d9e0f",
    required_scopes=["mcp:tool:call"],
    required_targets=["resource://pipernet"],
    require_session=True,
    revocations=revocations,
)

try:
    context = await auth.verify_token(token)
except CaracalAuthError as exc:
    raise RuntimeError(exc.code) from exc

The public entries are CaracalAuth and CaracalAuthError.

There is no Go FastMCP adapter; use the framework-neutral Go verifier or the net/http adapter.

Boundary

The adapter verifies tokens; it does not create Sessions or Delegations. Use the Python SDK or TypeScript SDK to create Caracal context before making outbound calls.

Related Pages

• Protect a FastMCP App
• Verify Package
• Sessions and Revocation