Framework Connectors
Framework connectors adapt the lower-level identity and MCP auth transport packages to common server frameworks. Use them before reaching for lower-level verification APIs.
Connector Map
Section titled “Connector Map”| Connector | Package | Use it for |
|---|---|---|
| Express | @caracalai/mcp-express | Protecting Express 5 routes with Caracal mandate verification. |
| ASGI | caracalai-asgi | Protecting FastAPI, Starlette, and other Python ASGI apps with Caracal mandate verification. |
| FastMCP | @caracalai/mcp-fastmcp, caracalai-mcp-fastmcp | Verifying FastMCP bearer tokens before tool execution. |
| Go net/http | github.com/garudex-labs/caracal/packages/connectors/nethttp/go | Protecting Go HTTP handlers. |
Choose a Verification Layer
Section titled “Choose a Verification Layer”| Need | Use |
|---|---|
| Framework-neutral verification | MCP Auth Transport |
| Express route middleware | Express Connector |
| FastAPI/Starlette (ASGI) middleware | ASGI Connector |
| FastMCP tool/server authentication | FastMCP Connector |
| Go HTTP middleware | Go net/http Connector |
| Shared revocation store | Redis Revocation Store |
Boundary Semantics
Section titled “Boundary Semantics”Every HTTP connector maps verification failures through one canonical status function in @caracalai/transport-mcp (httpStatusForAuthError in TypeScript, transportmcp.HTTPStatus in Go), so the boundary behaves identically across frameworks and languages:
- 401 — the credential itself was not accepted:
missing_token,invalid_token,invalid_zone,session_revoked,delegation_stale. - 403 — the mandate verified but its authority is insufficient for the route:
insufficient_scope,agent_required,delegation_required,chain_mismatch,hop_count_exceeded.
Connectors never re-derive these status codes; they consume the shared mapping.