MCP Client SDK

// Install (same package as the server SDK)
// npm install @modelcontextprotocol/sdksetup

// src/client-basic.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// ── 1. Create client ──────────────────────────────────────────────────────
const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  {
    capabilities: {
      // Declare what THIS CLIENT supports receiving
      // (for now we're read-only — no sampling, no roots)
    },
  }
);

// ── 2. Connect via stdio (spawn the server as a child process) ────────────
const transport = new StdioClientTransport({
  command: 'node',
  args: ['./dist/index.js'],              // path to your MCP server
  env: { ...process.env, GITHUB_TOKEN: process.env.GITHUB_TOKEN ?? '' },
});

await client.connect(transport);
console.log('Connected to:', client.getServerVersion());

// ── 3. Discover tools ─────────────────────────────────────────────────────
const { tools } = await client.listTools();
console.log(`\nAvailable tools (${tools.length}):`);
tools.forEach(t => console.log(`  • ${t.name} — ${t.description}`));

// ── 4. Call a tool ────────────────────────────────────────────────────────
const result = await client.callTool({
  name: 'search_repos',
  arguments: { query: 'modelcontextprotocol', cursor: 1 },
});

console.log('\nTool result:');
result.content.forEach(c => {
  if (c.type === 'text') console.log(c.text);
});

// ── 5. Always close ───────────────────────────────────────────────────────
await client.close();src/client-basic.ts

// src/client-resources-prompts.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({ name: 'explorer', version: '1.0.0' }, { capabilities: {} });
await client.connect(new StdioClientTransport({ command: 'node', args: ['./dist/index.js'] }));

// ── Resources ─────────────────────────────────────────────────────────────

// 1. List static resources
const { resources } = await client.listResources();
console.log('Static resources:', resources.map(r => r.uri));

// 2. List URI templates
const { resourceTemplates } = await client.listResourceTemplates();
console.log('Templates:', resourceTemplates.map(t => t.uriTemplate));

// 3. Read a static resource
const status = await client.readResource({ uri: 'devdash://status' });
const statusJson = JSON.parse(
  status.contents.find(c => c.mimeType === 'application/json')?.text ?? '{}'
);
console.log('Server status:', statusJson);

// 4. Read a URI template resource (expand the template first)
const repoData = await client.readResource({
  uri: 'github://repo/modelcontextprotocol/typescript-sdk',
});
console.log('Repo:', repoData.contents[0]?.text?.slice(0, 200));

// ── Prompts ───────────────────────────────────────────────────────────────

// 5. List available prompts
const { prompts } = await client.listPrompts();
console.log('Prompts:', prompts.map(p => p.name));

// 6. Render a prompt with arguments
const rendered = await client.getPrompt({
  name: 'code-review',
  arguments: {
    owner: 'modelcontextprotocol',
    repo: 'typescript-sdk',
    path: 'src/server/mcp.ts',
    focus: 'readability',
  },
});

// rendered.messages is a PromptMessage[] — send it straight to your LLM
console.log(`\nRendered ${rendered.messages.length} messages:`);
rendered.messages.forEach((m, i) => {
  const preview = m.content.type === 'text'
    ? m.content.text.slice(0, 80) + '…'
    : `[${m.content.type}]`;
  console.log(`  [${i}] role=${m.role}: ${preview}`);
});

await client.close();src/client-resources-prompts.ts

// src/client-capabilities.ts — safe capability-aware client
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client(
  { name: 'smart-client', version: '1.0.0' },
  {
    capabilities: {
      // Declare sampling support so the server knows it can call us back
      sampling: {},
    },
  }
);

await client.connect(new StdioClientTransport({ command: 'node', args: ['./dist/index.js'] }));

const caps = client.getServerCapabilities();
console.log('Server capabilities:', JSON.stringify(caps, null, 2));

// ── Guard before using optional features ─────────────────────────────────

// Only subscribe to resources if the server supports it
if (caps?.resources?.subscribe) {
  await client.subscribeResource({ uri: 'devdash://limits' });
  console.log('Subscribed to rate limits resource');
} else {
  console.log('Server does not support resource subscriptions — polling instead');
}

// Only set log level if server supports logging
if (caps?.logging) {
  await client.setLoggingLevel({ level: 'warning' });
  console.log('Log level set to warning');
}

// ── Handle server → client sampling requests ──────────────────────────────
// If the server calls sampling/createMessage, YOUR client must handle it.
// This is where you route to an LLM (Anthropic, OpenAI, etc.)
client.setRequestHandler(
  // The SDK exposes a type-safe handler setter for sampling
  { method: 'sampling/createMessage' } as any,
  async (request: any) => {
    const { messages, maxTokens, modelPreferences } = request.params;
    console.log('Server requested sampling:', messages[0]?.content);

    // In production: call your LLM here and return the response
    // For now, return a stub
    return {
      role: 'assistant',
      content: { type: 'text', text: 'Stub LLM response for sampling' },
      model: 'stub-model',
      stopReason: 'endTurn',
    };
  }
);

await client.close();src/client-capabilities.ts

// src/client-http.ts — connect to a remote HTTP+SSE MCP server
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

const client = new Client(
  { name: 'http-client', version: '1.0.0' },
  { capabilities: {} }
);

// Point at the SSE endpoint of the remote server
const transport = new SSEClientTransport(
  new URL('https://mcp.yourdomain.com/sse'),
  {
    // Auth headers injected on every request
    requestInit: {
      headers: {
        Authorization: `Bearer ${process.env.MCP_TOKEN}`,
      },
    },
  }
);

await client.connect(transport);

// From here it's identical to stdio — same methods, same types
const { tools } = await client.listTools();
console.log('Remote server tools:', tools.map(t => t.name));

const result = await client.callTool({
  name: 'search_repos',
  arguments: { query: 'mcp typescript' },
});
console.log(result.content[0]?.text);

await client.close();src/client-http.ts

// src/client-errors.ts — robust error handling patterns
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

async function safeCallTool(
  client: Client,
  name: string,
  args: Record<string, unknown>,
  timeoutMs = 30_000
) {
  // ── Timeout wrapper ──────────────────────────────────────────────────────
  const timeoutPromise = new Promise<never>((_, reject) =>
    setTimeout(() => reject(new Error(`Tool "${name}" timed out after ${timeoutMs}ms`)), timeoutMs)
  );

  let result;
  try {
    result = await Promise.race([
      client.callTool({ name, arguments: args }),
      timeoutPromise,
    ]);
  } catch (err) {
    // ── JSON-RPC / protocol errors ─────────────────────────────────────────
    if (err instanceof McpError) {
      switch (err.code) {
        case ErrorCode.MethodNotFound:
          throw new Error(`Tool "${name}" does not exist on this server`);
        case ErrorCode.InvalidParams:
          throw new Error(`Invalid arguments for tool "${name}": ${err.message}`);
        case ErrorCode.InternalError:
          throw new Error(`Server error executing "${name}": ${err.message}`);
        default:
          throw new Error(`MCP error ${err.code}: ${err.message}`);
      }
    }
    throw err; // re-throw transport errors, timeouts, etc.
  }

  // ── Tool domain errors (isError) ──────────────────────────────────────────
  if (result.isError) {
    const msg = result.content
      .filter(c => c.type === 'text')
      .map(c => c.text)
      .join('\n');
    // Tool errors are non-fatal — return them as structured data
    return { success: false, error: msg, content: result.content };
  }

  return { success: true, content: result.content };
}

// Usage
const res = await safeCallTool(client, 'search_repos', { query: 'mcp' });
if (!res.success) {
  console.warn('Tool returned error:', res.error);
} else {
  console.log(res.content[0]?.text);
}src/client-errors.ts

// src/client-multi.ts — orchestrate multiple MCP servers
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

// ── Connect to multiple servers ───────────────────────────────────────────
async function connectServer(name: string, transport: any): Promise<Client> {
  const client = new Client({ name: 'orchestrator', version: '1.0.0' }, { capabilities: {} });
  await client.connect(transport);
  console.log(`[${name}] Connected: ${client.getServerVersion()?.name}`);
  return client;
}

const [githubClient, dbClient, notifyClient] = await Promise.all([
  connectServer('github', new StdioClientTransport({
    command: 'node', args: ['./devdash-mcp/dist/index.js'],
    env: { ...process.env },
  })),
  connectServer('database', new StdioClientTransport({
    command: 'node', args: ['./db-mcp/dist/index.js'],
    env: { ...process.env },
  })),
  connectServer('notifications', new SSEClientTransport(
    new URL('https://notify.internal/sse'),
    { requestInit: { headers: { Authorization: `Bearer ${process.env.NOTIFY_TOKEN}` } } }
  )),
]);

// ── Build a unified tool registry ─────────────────────────────────────────
type ServerTool = { client: Client; serverName: string };
const toolRegistry = new Map<string, ServerTool>();

async function buildRegistry(client: Client, serverName: string) {
  const { tools } = await client.listTools();
  tools.forEach(t => toolRegistry.set(t.name, { client, serverName }));
  console.log(`[${serverName}] Registered ${tools.length} tools`);
}

await Promise.all([
  buildRegistry(githubClient, 'github'),
  buildRegistry(dbClient, 'database'),
  buildRegistry(notifyClient, 'notifications'),
]);

// ── Route tool calls to the right server ─────────────────────────────────
async function callTool(name: string, args: Record<string, unknown>) {
  const entry = toolRegistry.get(name);
  if (!entry) throw new Error(`No server provides tool: "${name}"`);
  console.log(`[route] ${name} → ${entry.serverName}`);
  return entry.client.callTool({ name, arguments: args });
}

// These automatically route to the correct server:
const repos    = await callTool('search_repos', { query: 'mcp' });
const records  = await callTool('query_users',  { limit: 10 });
const sent     = await callTool('send_slack',   { channel: '#dev', message: 'Repos fetched!' });

// ── Graceful shutdown ─────────────────────────────────────────────────────
await Promise.all([
  githubClient.close(),
  dbClient.close(),
  notifyClient.close(),
]);src/client-multi.ts

// src/client-notifications.ts — handle push events from the server
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client(
  { name: 'reactive-client', version: '1.0.0' },
  { capabilities: {} }
);

// ── Register notification handlers BEFORE connecting ─────────────────────
// (The SDK buffers notifications received before handlers are registered,
//  but best practice is to set handlers first.)

// 1. Tool list changed — rebuild your tool registry
client.setNotificationHandler(
  { method: 'notifications/tools/list_changed' } as any,
  async () => {
    const { tools } = await client.listTools();
    console.log('[notify] Tool list updated:', tools.map(t => t.name));
    // Re-populate your UI / route table here
  }
);

// 2. Resource updated — re-read the changed resource
client.setNotificationHandler(
  { method: 'notifications/resources/updated' } as any,
  async (notification: any) => {
    const { uri } = notification.params;
    console.log('[notify] Resource changed:', uri);
    const fresh = await client.readResource({ uri });
    console.log('[notify] New content length:', fresh.contents[0]?.text?.length);
  }
);

// 3. Log message from server — display in your UI
client.setNotificationHandler(
  { method: 'notifications/message' } as any,
  (notification: any) => {
    const { level, logger, data } = notification.params;
    const emoji = { debug:'🔍', info:'ℹ️', warning:'⚠️', error:'🔴' }[level] ?? '📝';
    console.log(`${emoji} [${logger ?? 'server'}] ${data}`);
  }
);

await client.connect(new StdioClientTransport({ command: 'node', args: ['./dist/index.js'] }));

// Subscribe to a resource to trigger update notifications
if (client.getServerCapabilities()?.resources?.subscribe) {
  await client.subscribeResource({ uri: 'devdash://limits' });
  console.log('Subscribed — will receive push updates');
}

// Keep alive (in a real app, your event loop keeps it running)
await new Promise(resolve => setTimeout(resolve, 60_000));src/client-notifications.ts

// Retry wrapper for transient tool errors
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

const RETRYABLE_CODES = new Set([ErrorCode.InternalError]);

async function callToolWithRetry(
  client: Client,
  name: string,
  args: Record<string, unknown>,
  maxRetries = 3
) {
  let delay = 300;
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await client.callTool({ name, arguments: args });
    } catch (err) {
      const isRetryable = err instanceof McpError && RETRYABLE_CODES.has(err.code);
      if (!isRetryable || attempt === maxRetries) throw err;
      const jitter = Math.random() * 200;
      console.warn(`[retry] ${name} attempt ${attempt} failed — retrying in ${delay}ms`);
      await new Promise(r => setTimeout(r, delay + jitter));
      delay *= 2;
    }
  }
}retry pattern