Skip to content

Express Connector

@caracalai/mcp-express protects Express routes by parsing the bearer token, verifying the mandate through @caracalai/transport-mcp, and attaching Caracal claims to the request.

Install

npm install @caracalai/mcp-express @caracalai/transport-mcp @caracalai/revocation-redis

The connector has an Express ^5.0.0 peer dependency and targets Node >=22.

Middleware

import express from "express";
import { caracalAuth } from "@caracalai/mcp-express";
import { createMandateVerifier } from "@caracalai/transport-mcp";
import { RedisRevocationStore } from "@caracalai/revocation-redis";

const app = express();

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

app.use("/mcp", caracalAuth({ verifier }, {
  requiredScopes: ["mcp:tool:call"],
  requiredTargets: ["https://mcp.example.com"],
  requireAgent: true,
}));

Request shape

The middleware attaches Caracal claims to req.caracal and req.caracalClaims when verification succeeds. Use the exported CaracalRequest type when a handler needs typed access.

import type { CaracalRequest } from "@caracalai/mcp-express";

app.post("/mcp/tools/search", (req: CaracalRequest, res) => {
  res.json({ subject: req.caracal?.sub });
});

Failure behavior

Failed verification returns an MCP transport error code such as missing_token, invalid_token, insufficient_scope, or session_revoked, plus a safe error_hint field. Pair the connector with a shared revocation store when multiple resource-server instances serve the same resource.