Skip to main content
Utilities for creating and managing connections to Model Context Protocol (MCP) servers using HTTP or STDIO transports.

​
Import

import {
  createHTTPClient,
  createSTDIOClient,
  listSTDIOClientTools,
  callSTDIOClientTool,
  disconnectSTDIOClient,
} from 'xmcp';

​
HTTP Client

​
createHTTPClient

Create a direct HTTP connection to an MCP server. 
async function createHTTPClient(
  options: HttpClientOptions
): Promise<Client<Request, Notification, Result>>
​
options
object
required
HTTP client configuration options.
Returns: Promise that resolves to a connected MCP Client instance.

​
Example

const client = await createHTTPClient({
  url: 'https://api.example.com/mcp',
  headers: {
    'Authorization': { env: 'API_TOKEN' },
    'X-Custom-Header': 'value',
  },
});

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

// Call a tool
const result = await client.callTool({
  name: 'search',
  arguments: { query: 'xmcp' },
});

​
STDIO Client

​
createSTDIOClient

Spawn and connect to an MCP server via STDIO transport. 
async function createSTDIOClient(
  options: StdioClientOptions
): Promise<StdioClientConnection>
​
options
object
required
STDIO client configuration options.
Returns: Promise that resolves to a StdioClientConnection object containing:
  • client: The connected MCP client instance
  • transport: The STDIO transport for manual control

​
Example

const connection = await createSTDIOClient({
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
  stderr: 'pipe',
  onStderrData: (chunk) => {
    console.error(`Server stderr: ${chunk.toString()}`);
  },
});

// Use the client
const tools = await connection.client.listTools();

​
listSTDIOClientTools

Convenience helper to list all tools available on a STDIO MCP server. 
async function listSTDIOClientTools(
  connection: StdioClientConnection
): Promise<string[]>
​
connection
StdioClientConnection
required
The connection object returned from createSTDIOClient.
Returns: Promise that resolves to an array of tool names.

​
Example

const connection = await createSTDIOClient({
  command: 'node',
  args: ['server.js'],
});

const toolNames = await listSTDIOClientTools(connection);
console.log('Available tools:', toolNames);

​
callSTDIOClientTool

Invoke a tool on the connected STDIO MCP server. 
async function callSTDIOClientTool(
  connection: StdioClientConnection,
  toolName: string,
  args: Record<string, unknown>
): Promise<unknown>
​
connection
StdioClientConnection
required
The connection object returned from createSTDIOClient.
​
toolName
string
required
Name of the tool to invoke.
​
args
Record<string, unknown>
required
Arguments to pass to the tool.
Returns: Promise that resolves to the tool’s result. Throws: Error if the tool call fails.

​
Example

const result = await callSTDIOClientTool(
  connection,
  'read_file',
  { path: '/tmp/example.txt' }
);

console.log('File contents:', result);

​
disconnectSTDIOClient

Disconnect the STDIO transport and close the client connection. 
async function disconnectSTDIOClient(
  connection: StdioClientConnection
): Promise<void>
​
connection
StdioClientConnection
required
The connection object to disconnect.
Throws: Error if disconnection fails.

​
Example

try {
  await disconnectSTDIOClient(connection);
  console.log('Disconnected successfully');
} catch (error) {
  console.error('Failed to disconnect:', error);
}

​
Complete STDIO example

import {
  createSTDIOClient,
  listSTDIOClientTools,
  callSTDIOClientTool,
  disconnectSTDIOClient,
} from 'xmcp';

async function main() {
  // Connect to MCP server
  const connection = await createSTDIOClient({
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
  });

  try {
    // List available tools
    const tools = await listSTDIOClientTools(connection);
    console.log('Available tools:', tools);

    // Call a tool
    const result = await callSTDIOClientTool(
      connection,
      'read_file',
      { path: '/tmp/data.json' }
    );
    console.log('Result:', result);
  } finally {
    // Always disconnect when done
    await disconnectSTDIOClient(connection);
  }
}

main().catch(console.error);

​
Client identity

All clients created by xmcp use consistent identity information: 
{
  name: 'xmcp',
  version: '0.0.1' // Package version
}

​
Client capabilities

Clients are initialized with the following MCP capabilities:
  • sampling: Full support
  • elicitation: Full support
  • roots: List changed notifications enabled

​
Transport configuration

​
HTTP transport

The HTTP client uses StreamableHTTPClientTransport with automatic reconnection:
  • Initial reconnection delay: 1000ms
  • Max reconnection delay: 30000ms
  • Delay growth factor: 1.5x
  • Max retries: 2

​
STDIO transport

The STDIO transport spawns a child process and communicates via stdin/stdout. Stderr is configurable and can be piped, inherited, or ignored.
Use stderr: "pipe" with onStderrData to capture and handle server logs separately from the MCP protocol messages.

​
Type definitions

// HTTP client types
type HttpClient = Awaited<ReturnType<typeof createHTTPClient>>;

interface HttpClientConfig {
  name?: string;
  type?: 'http';
  url: string;
  headers?: CustomHeaders;
}

// STDIO client types
type StdioClient = StdioClientConnection['client'];
type StdioIOStrategy = 'pipe' | 'inherit' | 'ignore';

interface StdioClientConfig {
  name?: string;
  type?: 'stdio';
  command?: string;
  args?: string[];
  npm?: string;
  npmArgs?: string[];
  env?: Record<string, string>;
  cwd?: string;
  stderr?: StdioIOStrategy;
}

interface StdioClientConnection {
  client: Client<Request, Notification, Result>;
  transport: StdioClientTransport;
}

Custom headers

Learn about custom header configuration

Client connections

Configure client connections in your server

Build docs developers (and LLMs) love

Get started for freeTalk to us