api-auth— agent skill

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.

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.

JWT config

Important: With MCP_AUTH_MODE=jwt, a missing MCP_AUTH_SECRET_KEY is a fatal startup error unless DEV_MCP_AUTH_BYPASS=true is explicitly set. Setting DEV_MCP_AUTH_BYPASS in production (NODE_ENV=production) is rejected at config parse time.

OAuth config

JWT claims mapping

Endpoints

CORS: Set MCP_ALLOWED_ORIGINS to a comma-separated list of allowed origins, or * for open access.

Stdio mode: No HTTP auth layer. Authorization is handled entirely by the host process.

Multi-tenancy

ctx.state is automatically scoped to the current tenant — no manual key prefixing needed.

tenantId sources

Tenant ID validation rules

• Max 128 characters
• Characters: alphanumeric, hyphens, underscores, dots
• Must start and end with an alphanumeric character
• No path traversal sequences (../)
• No consecutive dots (..)

Using ctx.state

handler: async (input, ctx) => {
  // Automatically scoped to ctx.tenantId — no manual prefixing
  await ctx.state.set('item:123', { name: 'Widget', count: 42 });
  const item = await ctx.state.get<Item>('item:123');
  await ctx.state.delete('item:123');

  const page = await ctx.state.list('item:', { cursor, limit: 20 });
  // page: { items: Array<{ key, value }>, cursor?: string }
},

ctx.state throws McpError(InvalidRequest) if tenantId is missing. In stdio mode, tenantId defaults to 'default' so ctx.state works without auth.

Auth context shape

Available on ctx.auth inside handlers (when auth is enabled):

interface AuthContext {
  clientId: string;        // Required — 'cid' or 'client_id' JWT claim
  scopes: string[];        // Required — derived from 'scp' or 'scope' claim
  sub: string;             // Required — 'sub' claim; falls back to clientId when absent
  token: string;           // Required — raw JWT or OAuth bearer token string
  tenantId?: string;       // Optional — 'tid' claim; present only for multi-tenant tokens
}

Access directly for conditional logic:

handler: async (input, ctx) => {
  const isAdmin = ctx.auth?.scopes.includes('admin:write') ?? false;
  // ...
},