api-auth

Overview

The framework handles auth at the handler factory level — tools and resources declare required scopes declaratively, and the framework enforces them before calling the handler. No try/catch or manual scope checking required for the common case.

---

Inline auth (primary pattern)

Declare required scopes directly on the tool or resource definition via the auth property. The handler factory checks ctx.auth.scopes against these before calling handler.

import { tool } from '@cyanheads/mcp-ts-core';

const myTool = tool('my_tool', {
  input: z.object({ query: z.string().describe('Search query') }),
  output: z.object({ result: z.string().describe('Search result') }),
  auth: ['tool:my_tool:read'],
  async handler(input, ctx) {
    // Only reached if caller has 'tool:my_tool:read' scope
  },
});

When MCP_AUTH_MODE=none, auth checks are skipped and defaults are allowed.

A failed check returns Forbidden (-32005, Insufficient permissions.) or, when auth is enabled but the request carries no auth context, Unauthorized (-32006). Neither carries data: the required, granted, and missing scope names stay in the server log, so a caller cannot enumerate scopes from the error.

The scope check logs a missing scope at warning, naming the missing scopes. On a tool, the call's Error in tool:<name> record follows at notice with no stack — the refusal is the caller's standing, not a fault in this server — and mcp.errors.classified counts it with mcp.error.severity: "notice". That holds for the inline check and for checkScopes in a handler alike, and the level is fixed: the refusal carries no data.reason, so no errors[] entry can set it. A missing auth context keeps its Error in tool: record at error, and so does a forbidden() the handler throws itself. A resource read the inline check refuses writes only the scope check's own records.

---

Dynamic auth

For runtime-computed scopes (e.g., scopes that depend on input values like a team or resource ID), use checkScopes from @cyanheads/mcp-ts-core/auth inside the handler: