---
title: "MCP Auth Transport"
url: "https://docs.caracal.run/sdks/transport-mcp/"
markdown_url: "https://docs.caracal.run/markdown/sdks/transport-mcp.md"
description: "Framework-neutral MCP authentication primitives for bearer parsing, mandate verification, and revocation checks."
page_type: "page"
concepts: []
requires: []
---

# MCP Auth Transport

Canonical URL: https://docs.caracal.run/sdks/transport-mcp/
Markdown URL: https://docs.caracal.run/markdown/sdks/transport-mcp.md
Description: Framework-neutral MCP authentication primitives for bearer parsing, mandate verification, and revocation checks.
Page type: page
Concepts: none
Requires: none

---

The MCP auth transport packages verify Caracal mandates without tying the check to Express, FastMCP, or Go net/http. Framework connectors build on this layer.

## Install

| Ecosystem | Package |
| --- | --- |
| TypeScript | `npm install @caracalai/transport-mcp` |
| Python | `pip install caracalai-transport-mcp` |
| Go | `go get github.com/garudex-labs/caracal/packages/transport/mcp/go` |

## Core APIs

| API | Purpose |
| --- | --- |
| `extractBearer` / `extract_bearer` / `ExtractBearer` | Parse a bearer token from an `Authorization` header. |
| `createMandateVerifier` / `NewVerifier` | Build a reusable verifier with secure defaults, JWKS caching, revocation checks, and per-route overrides. |
| `create_mandate_verifier` | Python reusable verifier with the same defaults, warmup, and per-route override model. |
| `authenticate` / `Authenticate` | Verify one token against identity claims and revocation anchors. |
| `checkActiveAuthority` / `check_active_authority` / `CheckActiveAuthority` | Check expiry and revoked anchors for verified claims. |

## TypeScript example

```ts
import { createMandateVerifier } from "@caracalai/transport-mcp";
import { InMemoryRevocationStore } from "@caracalai/revocation";

const verifier = createMandateVerifier({
  issuer: "https://sts.example.com",
  audience: "https://mcp.example.com",
  zoneId: "zone_prod",
  revocations: new InMemoryRevocationStore(),
});

const result = await verifier.authorization(req.headers.authorization, {
  requiredScopes: ["mcp:tool:call"],
  requiredTargets: ["https://mcp.example.com"],
  requireAgent: true,
});

if (!result.ok) {
  throw new Error(`${result.error.code}: ${result.error.hint}`);
}
```

Use one verifier per resource server and add route-level scopes or targets through `verifier.authorization(..., overrides)` or `verifier.require(overrides)`. The verifier defaults to resource mandates, checks the STS issuer and audience, enforces zone/scopes/targets/agent/delegation/hop constraints, checks expiry, and queries all revocation anchors for the session, root session, agent session, and delegation edge.

## Python example

```python
from caracalai_revocation import InMemoryRevocationStore
from caracalai_transport_mcp import AuthOptions, create_mandate_verifier

verifier = create_mandate_verifier(
    AuthOptions(
        issuer="https://sts.example.com",
        audience="https://api.example.com",
        expected_zone_id="zone_prod",
        revocations=InMemoryRevocationStore(),
    )
)

await verifier.warmup()

result = await verifier.authorization(
    request.headers.get("authorization"),
    required_scopes=["tickets:read"],
    required_targets=["https://api.example.com/tickets"],
)

if not result.ok:
    raise PermissionError(f"{result.error.code}: {result.error.hint}")
```

## Error codes

`authenticate` and reusable verifiers normalize failures into transport error codes: `missing_token`, `invalid_token`, `invalid_zone`, `insufficient_scope`, `session_revoked`, `agent_required`, `delegation_required`, `chain_mismatch`, and `hop_count_exceeded`. TypeScript, Python, and Go reusable verifiers include a safe debugging hint for operator logs and API error bodies.

## Related pages

- [Verification Layer Overview](/sdks/verification-layer/)
- [Protect an MCP Server](/guides/protect-mcp/)
- [Express Connector](/sdks/connectors/express/)
- [FastMCP Connector](/sdks/connectors/fastmcp/)
- [Go net/http Connector](/sdks/connectors/nethttp/)