Attest MCP

@attest-dev/sdk/mcp

Attest credential enforcement middleware for Model Context Protocol servers.

Two lines to protect every tool call on an existing MCP server.

Install

npm install @attest-dev/sdk

@attest-dev/sdk ships both the core client and the MCP middleware as a single package with two entry points.

Two-line integration

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

import { withAttest } from "@attest-dev/sdk/mcp";

const server = new McpServer({ name: "my-tools", version: "1.0.0" }); const protectedServer = withAttest(server, { issuerUri: "https://api.attest.dev", });

// Register tools exactly as before — every call is now credential-gated. protectedServer.tool("send_email", schema, handler);

withAttest patches server.tool() in place and returns the same server object typed as the original. Everything else — connect(), close(), transports — works unchanged.

How it works

On every tool call, before the handler executes:

1. Extract credential from extra.authInfo.token (MCP auth middleware path), extra.meta.attest_token, or extra.meta.authorization
2. Verify RS256 signature + expiry offline against the issuer's JWKS (fetched once, cached for 1 hour by default)
3. Map tool name → scope using scopeForTool() and check the credential's att_scope covers it
4. Check revocation via GET /v1/revoked/{jti} (10-second in-process cache)
5. Pass through to the original handler on success
6. Return a structured error on any failure — agent frameworks receive isError: true with a typed JSON payload
7. Fire audit event to POST /v1/audit — async, never blocks the tool call

Scope mapping

Tool names are automatically mapped to resource:action scope strings. The first word (before the first _) becomes the action; the remainder becomes the resource.

Action aliases — these raw prefixes map to canonical actions:

Multi-word resources keep their underscores in the scope string. get_weather_forecast → weather_forecast:read. This is intentional — the full noun phrase is preserved as the resource. When issuing credentials, use the same string: scope: ["weather_forecast:read"].

Override at registration — pass a AttestToolOptions object as the final argument to server.tool(). This is the preferred way to set scope for non-standard tool names because the scope lives next to the tool definition:

import { withAttest } from "@attest-dev/sdk/mcp";

import type { AttestToolOptions } from "@attest-dev/sdk/mcp";

protectedServer.tool("gh_create_issue", schema, handler, { requiredScope: "github:write", } satisfies AttestToolOptions);

protectedServer.tool("stripe_charge", schema, handler, { requiredScope: "stripe:write", } satisfies AttestToolOptions);

// Auto-mapping still applies when requiredScope is omitted. protectedServer.tool("send_email", schema, handler); // → "email:send"

The options object is consumed by withAttest and stripped before the MCP SDK sees the arguments — the SDK is unaware of it.

Override globally using toolScopeMap in options (applies to all tools that don't declare requiredScope explicitly):

const protectedServer = withAttest(server, {

issuerUri: "https://api.attest.dev", toolScopeMap: { "send_message": "slack:send", "query_db": "postgres:read", }, });

Scope discovery endpoint

getAttestScopes() returns the live scope registry — every tool name mapped to its resolved scope string. Wire it to an HTTP endpoint so credential issuers can query what scopes a server requires without out-of-band coordination.

import { withAttest, getAttestScopes } from "@attest-dev/sdk/mcp";

const protectedServer = withAttest(server, { issuerUri: "https://api.attest.dev" });

protectedServer.tool("send_email", schema, handler); protectedServer.tool("gh_create_issue", schema, handler, { requiredScope: "github:write" });

// Express / Hono / any HTTP framework: app.get("/.well-known/attest-scopes", (_req, res) => { res.json({ tools: getAttestScopes(protectedServer) }); });

Response:

{

"tools": { "send_email": "email:send", "gh_create_issue": "github:write" } }

An orchestrator agent issues credentials by fetching this endpoint first:

// Before starting a task, discover what the MCP server needs:

const { tools } = await fetch("https://my-mcp-server/.well-known/attest-scopes") .then(r => r.json());

// Issue a credential with exactly those scopes: const { token } = await attestClient.issue({ agent_id: "my-agent", user_id: "usr_alice", scope: Object.values(tools), // ["email:send", "github:write"] instruction: "...", });

No spreadsheet of scope strings. No manual sync between server and client. The server is the source of truth.

What an agent receives when blocked

{

"content": [ { "type": "text", "text": "{\n \"error\": \"attest_violation\",\n \"reason\": \"scope_violation\",\n \"detail\": \"Credential (jti: abc-123) grants [research:read] but tool \\\"send_email\\\" requires \\\"email:send\\\".\",\n \"jti\": \"abc-123\",\n \"taskId\": \"tid-xyz\"\n}" } ], "isError": true }

isError: true signals the MCP framework that this is an error response. The reason field is machine-readable:

Options

withAttest(server, {

// Required: URI of your Attest server issuerUri: "https://api.attest.dev",

// How long to cache JWKS before re-fetching (seconds). Default: 3600 jwksCacheTTL: 3600,

// How long to cache revocation status per JTI (seconds). // Set 0 to disable caching (every call hits the server). Default: 10 revocationCacheTTL: 10,

// false = log violations via onViolation but don't block the call. // Useful for gradual rollout. Default: true requireCredential: true,

// Per-tool scope overrides. Keys are exact tool names. toolScopeMap: { "send_message": "slack:send", },

// Called on every scope violation (synchronous). // Use for metrics, alerting, structured logging. onViolation: (event) => { console.warn("Attest violation", { tool: event.toolName, reason: event.reason, required: event.requiredScope, granted: event.grantedScope, jti: event.jti, }); }, });

Reading credential claims inside a tool handler

After withAttest has already verified the credential, use getAttestContext to read the claims without re-verifying:

import { withAttest, getAttestContext } from "@attest-dev/sdk/mcp";

protectedServer.tool("send_email", schema, async (args, extra) => { const ctx = getAttestContext(extra); // ctx.att_uid — the human who initiated the task // ctx.att_tid — task tree ID (use for audit correlation) // ctx.att_scope — granted scopes // ctx.att_depth — delegation depth (0 = root) // ctx.jti — this credential's unique ID

await sendEmail(args.to, args.body, { actingAs: ctx?.att_uid }); return { content: [{ type: "text", text: "sent" }] }; });

Gradual rollout

Add Attest to an existing server without blocking traffic until you're confident the mapping is correct:

const protectedServer = withAttest(server, {

issuerUri: "https://api.attest.dev", requireCredential: false, // observe, don't block onViolation: (event) => metrics.increment("attest.violation", { tool: event.toolName, reason: event.reason, }), });

Flip requireCredential to true once violation rates drop to zero in your monitoring.

Audit logging

Every tool call — pass or fail — fires a POST /v1/audit to your Attest server. Delivery is async and never blocks tool execution.

Audit delivery is best-effort with structured error surfacing. For guaranteed delivery, configure `onAuditError` and implement your own retry queue.

Failures surface in priority order — nothing is ever silently dropped:

1. `onAuditError(error, event)` — you handle it (retry queue, fallback log, pager)
2. `onViolation({ reason: "audit_failure", ... })` — surfaces to your existing monitoring if onAuditError is not set
3. `console.warn` — last resort if neither callback is configured

const protectedServer = withAttest(server, {

issuerUri: "https://api.attest.dev",

// Tier 1: implement a retry queue for guaranteed delivery onAuditError: (err, event) => { retryQueue.push({ event, attempts: 0, nextRetry: Date.now() + 5000 }); logger.error("attest audit delivery failed", { jti: event.jti, agent_id: event.agent_id, error: err.message, }); },

// Tier 2: violations (including audit_failure) go to your monitoring onViolation: (e) => metrics.increment("attest.event", { reason: e.reason }), });

Non-2xx responses from the audit endpoint are treated as delivery failures, not silent successes.

The audit event carries: event_type, jti, att_tid, att_uid, agent_id (mcp: ), scope, and an outcome meta field (allowed, scope_violation, blocked_revoked).

Query the audit chain for a task tree:

import { AttestClient } from "@attest-dev/sdk";

const client = new AttestClient({ baseUrl: "https://api.attest.dev", apiKey: "..." }); const chain = await client.audit(taskId); chain.events.forEach(e => console.log(e.event_type, e.jti, e.created_at));

Full example

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { withAttest } from "@attest-dev/sdk/mcp"; import { z } from "zod";

const server = new McpServer({ name: "email-server", version: "1.0.0" });

server.tool( "send_email", { to: z.string().email(), subject: z.string(), body: z.string() }, async ({ to, subject, body }) => { await sendEmail(to, subject, body); return { content: [{ type: "text", text: Sent to ${to} }] }; }, );

// Wrap — every tool now requires a valid credential with "email:send" scope. const protectedServer = withAttest(server, { issuerUri: process.env.ATTEST_URI ?? "http://localhost:8080", onViolation: (e) => console.warn("blocked:", e.reason, e.toolName), });

const transport = new StdioServerTransport(); await protectedServer.connect(transport);

License

Apache-2.0