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.

---

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:

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

handler: async (input, ctx) => {
  checkScopes(ctx, [`team:${input.teamId}:write`]);
  // Continues only if scope is satisfied
},

Signature: checkScopes(ctx: Context, requiredScopes: string[]): void

Throws:

• McpError(Forbidden) — auth is active and one or more required scopes are missing
• McpError(Unauthorized) — auth is enabled but no auth context exists on the request
• No-ops when MCP_AUTH_MODE=none

---

Auth modes

Set via MCP_AUTH_MODE environment variable.

Mode	Value	Behavior
Disabled	none	No auth enforcement. All requests allowed.
JWT	jwt	Local secret verification via MCP_AUTH_SECRET_KEY. Requires explicit DEV_MCP_AUTH_BYPASS=true to bypass in development.
OAuth	oauth	JWKS verification against an external issuer.