@mcp-z/client

Programmatic MCP client library for Node.js - connect, discover, and call tools on Model Context Protocol servers.

Common uses

• Run MCP tools from scripts
• Connect to multiple servers in one process
• Integration tests for MCP servers

Install

npm install --save-dev @mcp-z/client

Requires Node.js >= 22.

Quick start

import { createServerRegistry } from '@mcp-z/client';

const registry = createServerRegistry({
  todoist: { type: 'http', url: 'https://ai.todoist.net/mcp' }
});

const client = await registry.connect('todoist');
await client.callTool('add-tasks', {
  tasks: [{ content: 'Learn MCP', priority: 4 }]
});

await registry.close();

Configuration

MCP supports stdio and HTTP.

Stdio

{
  echo: {
    command: 'node',
    args: ['server.js'],
    env: { LOG_LEVEL: 'info' }
  }
}

HTTP

{
  todoist: {
    type: 'http',
    url: 'https://ai.todoist.net/mcp',
    headers: { Authorization: 'Bearer token' }
  }
}

HTTP with start block (extension)

Use dialects: ['start'] to spawn HTTP servers with start blocks.

const registry = createServerRegistry(
  {
    api: {
      type: 'http',
      url: 'http://localhost:3000/mcp',
      start: { command: 'node', args: ['server.js'] }
    }
  },
  { dialects: ['start'] }
);

API overview

Registry

• createServerRegistry(config, options?)
• registry.connect(name, options?)
• registry.searchCapabilities(query, options?)
• registry.close()

Managed client

• client.callTool(name, args)
• client.getPrompt(name, args)
• client.readResource(uri)
• client.listTools() / client.listResources() / client.listPrompts()
• client.callToolRaw() / client.getPromptRaw() / client.readResourceRaw() (raw SDK responses)

Response helpers

Tool, prompt, and resource calls return wrappers with:

• json() - Parse structured content
• text() - First text result
• raw() - Raw MCP response

Examples

Call a tool

const response = await client.callTool('drive-search', { query: 'Q4 Reports' });
const data = response.json();

Get a prompt

const prompt = await client.getPrompt('query-syntax', { service: 'gmail' });
console.log(prompt.text());

Read a resource

const resource = await client.readResource('mcp-pdf://abc123');
console.log(resource.text());

Search capabilities

const results = await registry.searchCapabilities('message send', {
  types: ['tool'],
  servers: ['gmail', 'outlook']
});

createServerRegistry options

• cwd - Working directory for spawned processes (default: process.cwd())
• env - Base env for all servers (if set, process.env is not merged)
• dialects - Which servers to spawn: ['servers'] (stdio), ['start'] (HTTP start blocks), or both

OAuth (DCR)

If an HTTP server supports DCR, pass a token store via dcrAuthenticator:

import Keyv from 'keyv';
import { createServerRegistry } from '@mcp-z/client';

const registry = createServerRegistry({
  todoist: { type: 'http', url: 'https://ai.todoist.net/mcp' }
});

const client = await registry.connect('todoist', {
  dcrAuthenticator: { tokenStore: new Keyv() }
});

Requirements

• Node.js >= 22

Documentation

API Docs