Tool context

Reference for the ToolContext object passed to every tool handler, including authentication, session, and cancellation properties.

Overview

Every tool handler receives a ToolContext as its second argument. It carries the current session ID, resolved authentication headers, provider token, and an abort signal for cancellation.

handler: async (args: z.infer<TSchema>, context: ToolContext) => { ... }

Properties

sessionId · string

The current MCP session ID. Generated by the server on the initialize handshake. Use this to correlate tool calls to a specific client session in logs or external systems.

signal · AbortSignal | undefined

An AbortSignal for cooperative cancellation. When the MCP client sends a notifications/cancelled message, the server aborts the signal. Pass this to fetch or other async operations so they stop early when the client cancels.

handler: async (args, context) => {
  const res = await fetch("https://api.example.com/data", {
    signal: context.signal,
  });
  return res.json();
},

meta · { progressToken?: string | number; requestId?: string } | undefined

Request metadata forwarded from the MCP JSON-RPC layer.

• progressToken — opaque token the client uses to track progress notifications.
• requestId — the JSON-RPC request ID for this call.

authStrategy · 'oauth' | 'bearer' | 'api_key' | 'custom' | 'none' | undefined

The active authentication strategy for this server instance.

Value	Description
oauth	Full OAuth 2.1 PKCE flow; providerToken is the mapped provider access token
bearer	Static bearer token from BEARER_TOKEN env var
api_key	Static API key from API_KEY env var
custom	Arbitrary headers from CUSTOM_HEADERS env var
none	No authentication configured

providerToken · string | undefined

The resolved access token for the authenticated user.

• OAuth: the provider access token mapped from the RS token (e.g., a Google or GitHub token).
• Bearer: the value of the BEARER_TOKEN environment variable.
• API key: the value of the API_KEY environment variable.
• Custom / none: undefined.

Use resolvedHeaders for making API calls instead of constructing the Authorization header yourself.

provider · ProviderInfo | undefined

OAuth provider details. Only populated when authStrategy is oauth.

interface ProviderInfo {
  accessToken: string;
  refreshToken?: string;
  expiresAt?: number;
  scopes?: string[];
}

resolvedHeaders · Record<string, string> | undefined

Ready-to-use HTTP headers for forwarding authentication to external APIs. The exact headers depend on the active strategy:

Strategy	Header
oauth	Authorization: Bearer <provider-token>
bearer	Authorization: Bearer <BEARER_TOKEN>
api_key	<API_KEY_HEADER>: <API_KEY> (default header: x-api-key)
custom	All headers from CUSTOM_HEADERS env var

Spread or pass this object directly to fetch:

handler: async (args, context) => {
  const response = await fetch("https://api.example.com/me", {
    headers: context.resolvedHeaders,
  });
  return response.json();
},

authHeaders · Record<string, string> | undefined · deprecated

Raw authorization headers from the incoming MCP request (before resolution). Use resolvedHeaders instead — it contains the correct auth headers for forwarding to external services regardless of the active strategy.

AuthenticatedToolContext

AuthenticatedToolContext extends ToolContext and guarantees that providerToken is a non-optional string. The dispatcher populates this automatically for tools that declare requiresAuth: true.

interface AuthenticatedToolContext extends ToolContext {
  providerToken: string;
}

You can also use assertProviderToken to narrow the type manually:

import { assertProviderToken } from "@phake/mcp";

handler: async (_args, context) => {
  assertProviderToken(context);
  // context.providerToken is now string, not string | undefined
},

Examples

Forward auth to an external API

import { defineTool } from "@phake/mcp";
import { z } from "zod";

export const getProfileTool = defineTool({
  name: "get_profile",
  description: "Fetch the authenticated user's profile",
  inputSchema: z.object({}),
  requiresAuth: true,
  handler: async (_args, context) => {
    const response = await fetch("https://api.example.com/me", {
      headers: context.resolvedHeaders,
      signal: context.signal,
    });
    if (!response.ok) {
      return { error: `HTTP ${response.status}` };
    }
    return response.json();
  },
});

Use session ID for logging

handler: async (args, context) => {
  console.log(`[${context.sessionId}] Calling search with query: ${args.query}`);
  // ...
},

Inspect auth strategy

handler: async (args, context) => {
  if (context.authStrategy === "none") {
    return { error: "Authentication is not configured on this server" };
  }
  // continue with authenticated logic
},