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: