@modelcontextprotocol/client

Establishes and manages bidirectional message transport between MCP clients and servers using JSON-RPC 2.0 protocol over stdio, HTTP, or custom transports. Implements automatic message serialization/deserialization, request-response correlation via message IDs, and error handling with typed error responses. Handles both synchronous request-response patterns and asynchronous server-initiated notifications through a unified message queue and event dispatcher.

Provides typed tool calling with automatic JSON schema validation, parameter marshaling, and result handling. Client maintains a registry of available tools discovered from the server during initialization, validates incoming tool calls against their declared schemas, and routes execution to the appropriate handler. Supports both synchronous and asynchronous tool implementations with error propagation back to the LLM.

Builds and maintains typed registries for tools, resources, and prompts discovered from the server, enabling type-safe access and validation. Each registry entry includes metadata (name, description, schema), and the client provides typed methods to look up and invoke capabilities. TypeScript types are generated from server-provided schemas, enabling IDE autocomplete and compile-time type checking.

Provides a promise-based API for making requests to the server, with automatic message ID generation, request tracking, and response correlation. Each request returns a promise that resolves with the response or rejects with an error. Supports timeout handling and cancellation via AbortController.

Manages access to server-exposed resources (files, documents, database records) through URI-based addressing with template expansion. Client maintains a resource list from the server, resolves URI templates with provided arguments, and fetches resource contents with automatic caching and refresh semantics. Supports both read-only resource access and resource listing with filtering.

Manages reusable prompt templates exposed by the server, with support for argument substitution, composition, and versioning. Client discovers available prompts during initialization, renders them with provided arguments, and can chain multiple prompts together. Supports both simple string templates and complex prompts with embedded tool calls and resource references.

Implements the MCP initialization handshake that discovers server capabilities (tools, resources, prompts) and negotiates protocol version and features. Client sends an initialize request with its own capabilities, receives the server's capability list, and builds internal registries for tools, resources, and prompts. Handles version negotiation and feature flags to ensure compatibility.

Manages stdio-based transport for MCP servers running as local subprocesses. Spawns server processes, handles stdin/stdout communication with line-buffered JSON message exchange, manages process lifecycle (startup, shutdown, restart), and provides error handling for process crashes. Implements automatic reconnection and graceful shutdown with timeout handling.

Implements HTTP-based transport for MCP servers accessible via HTTP endpoints. Sends JSON-RPC requests as HTTP POST bodies, correlates responses via message IDs, and handles HTTP-specific concerns like timeouts, retries, and connection pooling. Supports both request-response patterns and server-sent events (SSE) for server-initiated notifications.

Implements comprehensive error handling with typed error responses following JSON-RPC 2.0 error specification. Distinguishes between protocol errors (invalid requests, parse errors), server errors (tool execution failures, resource not found), and transport errors (connection failures, timeouts). Provides structured error objects with error codes, messages, and optional error data for programmatic handling.

Manages an internal message queue for incoming messages and dispatches them to appropriate handlers based on message type (request, response, notification). Implements request-response correlation via message IDs, ensuring responses are routed to the correct pending requests. Provides event emitters for notifications and server-initiated messages, enabling event-driven application logic.

Manages the full connection lifecycle including initialization, capability negotiation, active communication, and graceful shutdown. Implements connection state tracking (connecting, connected, disconnected), timeout handling for initialization and requests, and cleanup of resources on disconnect. Provides hooks for connection state changes to enable application-level logic.