Model Context Protocol TypeScript SDK

The stickynotes example is a capstone application designed to demonstrate complex Model Context Protocol (MCP) interactions. It implements a sticky-notes board where:

• Tools mutate state: Tools are used to modify the board.
• Resources represent state: Each individual note is treated as an MCP resource.
• Dynamic resource lists: The list of available resources changes dynamically when notes are added or removed.
• Elicitation flows: The remove_all tool demonstrates a destructive action that requires user confirmation (elicitation).

Note on transport compatibility:

• stdio/legacy: Supports the full flow, including the cancel / unchecked / confirm elicitation cycle.
• Modern/HTTP legs: Support add, list, read, and remove operations, but skip the remove_all confirmation flow due to transport limitations (e.g., the lack of a server→client request channel in certain eras or the stateless nature of HTTP handlers).

The repository contains numerous examples categorized by what they teach. Use these to understand specific MCP capabilities:

Core Concepts

• tools: Registering tools, inferring schemas, and structured output.
• prompts: Working with prompts and argument completion.
• resources: Static and templated resources, listing, reading, and subscriptions.
• dual-era: How to implement a single factory that supports both protocol eras and transports.

Advanced Features

• subscriptions: Using client.listen() and handler.notify for real-time updates.
• streaming: Implementing in-flight progress, logging, and cancellation.
• elicitation: Handling user input via form or URL modes (supports both 2025 push-style and 2026 inputRequired).
• sampling: Requesting LLM sampling from the client.
• caching: Using cacheHints for cacheable results.
• gateway: Implementing the gateway pattern using connect({ prior }) for zero-round-trip connections.
• auth: Implementing Bearer token authentication and OAuth (authorization_code and client_credentials).

The MCP TypeScript SDK follows Semantic Versioning 2.0.0. Because it is a monorepo, packages are organized into version groups to ensure compatibility:

• Fixed Group: The following packages always release together with the same version number:

  • @modelcontextprotocol/core
  • @modelcontextprotocol/client
  • @modelcontextprotocol/server
  • @modelcontextprotocol/server-legacy
  • @modelcontextprotocol/codemod

• Framework Integrations: Packages like @modelcontextprotocol/node, @modelcontextprotocol/express, @modelcontextprotocol/hono, and @modelcontextprotocol/fastify are versioned alongside the fixed group. They bump when their @modelcontextprotocol/server peer dependency range changes, or independently for their own changes.

• Internal/Private: @modelcontextprotocol/core-internal and the @modelcontextprotocol/core/internal entry point are private. They carry no compatibility promises and may change in any release without notice.

The completion callback for a completable argument can accept an optional second parameter containing context. This context includes arguments, which are the values the client has already filled in for the prompt's other arguments. This allows you to create dependent autocompletions (e.g., selecting a branch based on a previously selected repository).

Note: Clients are not required to send context. Your callback should handle cases where context or context.arguments is missing by returning an empty list rather than throwing an error.

async function completeBranch(value: string, context?: { arguments?: Record<string, string> }): Promise<string[]> {
    // Access previously filled arguments
    const repo = context?.arguments?.repo;
    if (!repo) return [];
    
    // Return suggestions filtered by the context
    return (branchesByRepo[repo] ?? []).filter(branch => branch.startsWith(value));
}

To support multiple authorization servers, v2 uses an issuer stamp on persisted credentials. When auth() is used, it adds an issuer field to every value passed to saveTokens() and saveClientInformation().

Implementation Requirements for OAuthClientProvider implementers:

1. Round-trip the issuer stamp: Your storage implementation must persist the object returned by saveTokens / saveClientInformation verbatim and return it exactly as received. If you rebuild the object field-by-field and drop the issuer, the SDK will log an [mcp-sdk] warning and the per-AS issuer check will not apply.
2. Key storage by issuer: To hold credentials for multiple authorization servers, key your storage using ctx.issuer.
   • Note: If ctx is undefined, it signifies a request to return the most-recently-saved token set (used by the transport's per-request Authorization: Bearer calls).
3. Handle Discovery State: Implement discoveryState() and saveDiscoveryState() so the authorization-server metadata survives restarts. This allows the callback leg to verify it is exchanging the code at the same AS that the redirect targeted.

New Types:

• StoredOAuthTokens and StoredOAuthClientInformation now include an optional issuer?: string field.

// Example of implementing discovery state on OAuthClientProvider
class MyProvider implements OAuthClientProvider {
  async saveDiscoveryState(state: OAuthDiscoveryState): Promise<void> {
    // Persist state with same durability as codeVerifier
  }

  async discoveryState(): Promise<OAuthDiscoveryState | undefined> {
    // Return persisted state
  }
}

An MCP host (like VS Code, Cursor, or Claude Code) interacts with an MCP server as a child process using stdin and stdout.

The Lifecycle of a Tool Call:

1. Discovery: The host sends the model the names, descriptions, and input schemas of all available tools.
2. Decision: The model selects a tool based on the user's prompt and the tool's metadata.
3. Request: The host (acting as an MCP client) sends a tools/call request to the server over stdin.
4. Execution: The server's SDK validates the arguments against the inputSchema and executes the handler.
5. Response: The server sends the result back over stdout as a tools/call result.
6. Completion: The model reads the result and generates a natural language response for the user.

Critical Constraint: stdout is reserved strictly for the JSON-RPC protocol. Any logging to stdout will break the connection. Use stderr for all diagnostic logging.