MCP Client

A lightweight, framework-agnostic TypeScript client for the Model Context Protocol (MCP).

Installation

npm install @anthropic/mcp-client

Quick Start

import { McpClient } from '@anthropic/mcp-client';

const client = new McpClient({
  baseUrl: 'http://localhost:3000/mcp',
  clientInfo: { name: 'my-app', version: '1.0.0' },
  debug: true,
});

// Connect to the server
await client.connect();

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.map(t => t.name));

// Call a tool
const result = await client.callTool('my-tool', { query: 'hello' });
console.log('Result:', result);

API Reference

Constructor

new McpClient(config: McpClientConfig)

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseUrl | string | required | MCP server URL | | clientInfo | { name, version } | { name: 'mcp-client', version: '1.0.0' } | Client identification | | protocolVersion | string | '2024-11-05' | MCP protocol version | | capabilities | object | {} | Capabilities to advertise | | debug | boolean | false | Enable debug logging |

Methods

Connection

• connect(): Promise<void> — Connect and initialize session
• disconnect(): void — Clear session
• isConnected(): boolean — Check connection status
• getActiveSessionId(): string | null — Get current session ID
• ping(): Promise<boolean> — Check server health

Tools

• listTools(): Promise<McpTool[]> — List available tools
• callTool(name: string, args: object): Promise<McpToolCallResult> — Execute a tool

Resources

• listResources(): Promise<McpResource[]> — List available resources
• readResource(uri: string): Promise<any> — Read a resource

Prompts

• listPrompts(): Promise<McpPrompt[]> — List available prompts
• getPrompt(name: string, args?: object): Promise<any> — Get a prompt

Events

Subscribe to client events:

const unsubscribe = client.on((event) => {
  switch (event.type) {
    case 'connected':
      console.log('Connected with session:', event.sessionId);
      break;
    case 'disconnected':
      console.log('Disconnected');
      break;
    case 'session-expired':
      console.log('Session expired, will auto-reconnect');
      break;
    case 'error':
      console.error('Error:', event.error);
      break;
  }
});

// Later: unsubscribe()

Types

interface McpTool {
  name: string;
  description?: string;
  inputSchema: {
    type: string;
    properties?: Record<string, any>;
    required?: string[];
  };
}

interface McpToolCallResult {
  content: Array<{
    type: string;
    text?: string;
  }>;
  isError?: boolean;
}

interface McpResource {
  uri: string;
  name: string;
  description?: string;
  mimeType?: string;
}

interface McpPrompt {
  name: string;
  description?: string;
  arguments?: Array<{
    name: string;
    description?: string;
    required?: boolean;
  }>;
}

Features

• Zero dependencies — Only uses native fetch
• TypeScript-first — Full type definitions included
• Auto-reconnect — Handles session expiration automatically
• Framework-agnostic — Works with any LLM provider (OpenAI, Anthropic, Google, etc.)
• Browser & Node.js — Works in both environments

License

MIT