External Clients

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

xmcp lets you connect to external MCP servers and generate fully typed clients. The CLI generates TypeScript clients with autocomplete for all tools exposed by HTTP or STDIO-based MCP servers. For production deployments, use the HTTP transport. STDIO is limited to local development because it cannot be deployed in production environments.

Managed connections

Use the Node.js xmcp/client entry to connect directly without generating a typed client. createClient accepts a ClientDefinition and selects HTTP or STDIO from its type. It returns the connected SDK client, with methods such as listTools, callTool, readResource, and getPrompt.

import { createClient } from "xmcp/client";

const client = await createClient({
  type: "http",
  name: "local",
  url: "http://localhost:3001/mcp",
});
try {
  const { tools } = await client.listTools();
  console.log(tools);
} finally {
  await client.close();
}

withClient(definition, operation, options?) closes the connection after the callback resolves or throws and returns its result. Failed connections also clean up before rejecting. Closing a STDIO client waits for the spawned server process to exit.

import { withClient } from "xmcp/client";

const tools = await withClient(
  {
    type: "stdio",
    name: "local",
    command: "node",
    args: ["./dist/stdio.js"],
  },
  async (client) => (await client.listTools()).tools
);

These definitions use an explicit name, type, and, for STDIO, command and args. The shorthand npm and URL entries in src/clients.ts below are resolved by the generator; pass a resolved ClientDefinition to the managed API. HTTP headers support the same static values and environment references shown below. STDIO definitions support env, cwd, and stderr. Stderr is inherited by default; passing onStderrData in the options pipes it to your callback unless the definition explicitly selects another stderr strategy. An explicitly piped stream without a callback is forwarded to the parent's stderr.

Client handlers

Pass handlers in the options to support sampling, elicitation, or roots. They are registered before connecting, and only configured capabilities are advertised. Without handlers, none of these optional capabilities are advertised.

import { withClient } from "xmcp/client";

await withClient(
  { type: "http", name: "local", url: "http://localhost:3001/mcp" },
  (client) => client.callTool({ name: "confirm" }),
  {
    handlers: {
      // A real application can display the request and collect the user's choice.
      elicitation: (request) => {
        console.log(request.params.message);
        return { action: "cancel" };
      },
      roots: () => ({
        roots: [{ uri: "file:///workspace", name: "Workspace" }],
      }),
    },
  }
);

handlers.sampling handles sampling/createMessage, handlers.elicitation handles elicitation/create (both form and URL modes), and handlers.roots handles roots/list. Each receives the SDK request and client context and may return a result or a promise. A sampling handler must return the SDK's sampling result, including role, content, and model; supplying one advertises basic sampling support. Roots handlers do not advertise automatic list-change notifications.

Connections negotiate the protocol automatically. You can pass versionNegotiation: { mode: "legacy" } to force the older handshake. On modern connections, the SDK also routes embedded input_required requests through these handlers and retries the operation. Legacy stateless HTTP cannot deliver server-to-client input requests.

Cancellation and connection limits

Pass SDK request options directly to client methods. The connect option applies to connection setup:

import { withClient } from "xmcp/client";

const controller = new AbortController();
const CONNECTION_TIMEOUT_MS = 10_000; // Bound initial connection setup.
await withClient(
  { type: "http", name: "local", url: "http://localhost:3001/mcp" },
  (client) =>
    client.callTool(
      { name: "long-running-task" },
      { signal: controller.signal }
    ),
  { connect: { timeout: CONNECTION_TIMEOUT_MS, signal: controller.signal } }
);

Call controller.abort() from your application's cancel action. Modern HTTP and STDIO propagate cancellation to the server handler. Legacy stateless HTTP cannot route cancellation notifications to an earlier request. The managed client preserves that transport limitation.

With SDK 2.0.0 servers, cancellation of numeric request ID 0 is ignored. This can affect the first operation on a modern STDIO connection. Call listTools() before starting cancellable work on those servers; this is an underlying SDK limitation.

The existing createHTTPClient, createSTDIOClient, and generated clients keep their current behavior. For a runnable managed-client script, see the external-clients example.

Inspecting servers from the CLI

Use inspect to see a server's identity, negotiated protocol version, capabilities, and instructions. Use list to discover its tools, prompts, resources, and resource templates:

npx @xmcp-dev/cli inspect http://localhost:3001/mcp
npx @xmcp-dev/cli list http://localhost:3001/mcp --json

Both commands also accept a client name from src/clients.ts (falling back to clients.ts). Named clients preserve configured headers, environment variables, and STDIO settings. Override the file with -c, --clients:

npx @xmcp-dev/cli inspect context --json
npx @xmcp-dev/cli list context --clients config/clients.ts --json

To launch a local server directly, use --stdio. Put the CLI's options before --stdio; all arguments after the executable are passed to the server unchanged:

npx @xmcp-dev/cli inspect --json --stdio node ./dist/stdio.js
npx @xmcp-dev/cli list --json --stdio node ./dist/stdio.js

inspect --json returns serverInfo, protocolVersion, capabilities, and instructions. list --json returns tools, prompts, resources, and resourceTemplates, preserving metadata and schemas and following pagination. Capabilities the server does not advertise produce empty arrays.

Stdout contains the result only; logs and errors go to stderr. Configuration, connection, and listing failures exit nonzero without printing a partial result. Connections close before output is printed, including subprocess cleanup for STDIO. These commands negotiate modern or legacy MCP automatically and discover metadata without calling tools or fetching resource contents.

The external-clients example includes pnpm inspect and pnpm list:server scripts for a local server.

Executing operations from the CLI

call, read-resource, and get-prompt use the same URL, named-client, and STDIO connections as inspect and list. Each prints the complete MCP result as JSON, including content blocks, structured content, messages, and metadata:

npx @xmcp-dev/cli call http://localhost:3001/mcp greet --arg name=Ada
npx @xmcp-dev/cli call local add --arg a=2 --arg b=3
npx @xmcp-dev/cli call local add --args-file args.json
printf '{"a":2,"b":3}\n' | npx @xmcp-dev/cli call local add --stdin
npx @xmcp-dev/cli read-resource local 'config://app'
npx @xmcp-dev/cli get-prompt local team-greeting --arg department=engineering --arg name=Ada

Define local in your client config, or replace it with a server URL. For a direct STDIO server, omit the target and put all CLI options before --stdio:

npx @xmcp-dev/cli call add --arg a=2 --arg b=3 --stdio node ./dist/stdio.js

Tool --arg key=value values parse as JSON when possible, otherwise as strings. Use --arg 'id="123"' to send a numeric-looking string. Prompt --arg values stay strings; prompt JSON objects must also contain string values.

Use one argument source per command: repeated --arg, --args-file, or stdin. --stdin and --args-file - explicitly read stdin. Without argument options, piped stdin is read automatically; empty automatic stdin means no arguments. Files and nonempty stdin must contain a JSON object. Duplicate keys in repeated --arg options are rejected. read-resource takes a complete URI, including resolved resource-template parameters, and accepts no argument options.

Tool arguments are checked against the advertised JSON Schema before invocation. Prompts validate required argument names and string values. --json is optional because execution results are always JSON.

Logs and diagnostics go to stderr. Connections close before printing, including on errors; STDIO subprocesses are terminated. These commands do not install sampling or elicitation handlers. Use the managed-client API when your server needs those interactions.

The external-clients example includes runnable call:server, read:server, and prompt:server scripts.

Creating the Clients File

Create a src/clients.ts file and export a ClientConnections object. The object keys become the client names:

import { ClientConnections } from "xmcp";

export const clients: ClientConnections = {
  context: {
    url: "https://mcp.context7.com/mcp",
    headers: [{ name: "CONTEXT7_API_KEY", env: "CONTEXT7_API_KEY" }],
  },
  playwright: {
    npm: "@playwright/mcp",
  },
};

HTTP Clients (recommended)

HTTP clients connect to remote MCP servers over HTTP. This is the recommended transport for production deployments.

type HttpClientConfig = {
  name?: string; // Optional, defaults to object key
  type?: "http"; // Optional, inferred from url
  url: string; // MCP server URL (required)
  headers?: CustomHeaders; // Optional headers array
};

type CustomHeaders = CustomHeader[];

type CustomHeader = StaticHeader | EnvHeader;

// Static value (non-sensitive)
interface StaticHeader {
  name: string;
  value: string;
}

// Environment variable (sensitive values like API keys)
interface EnvHeader {
  name: string;
  env: string; // Environment variable name to read at runtime
}

Example:

{
  context: {
    url: "https://mcp.context7.com/mcp",
    headers: [
      { name: "CONTEXT7_API_KEY", env: "CONTEXT7_API_KEY" },
    ],
  },
}

To make HTTP extra.clientInfo available on stateless tool calls, repeat client identity in the current request headers:

{
  assistant: {
    url: "https://example.com/mcp",
    headers: [
      { name: "x-mcp-client-name", value: "my-client" },
      { name: "x-mcp-client-version", value: "1.0.0" },
      { name: "x-mcp-client-title", value: "My Client" },
    ],
  },
}

STDIO Clients (local servers)

STDIO clients spawn local processes that communicate via standard input/output.

type StdioClientConfig = {
  name?: string; // Optional, defaults to object key
  type?: "stdio"; // Optional, inferred from npm/command
  command?: string; // Command to run (e.g., "npx", "bunx", "node")
  args?: string[]; // Command arguments
  npm?: string; // npm package to run via npx
  npmArgs?: string[]; // Arguments to pass to npm package
  env?: Record<string, string>; // Environment variables
  cwd?: string; // Working directory
  stderr?: "pipe" | "inherit" | "ignore"; // Stderr handling
};

Examples:

// Simple npm package
{ npm: "@playwright/mcp" }

// With arguments
{ npm: "@playwright/mcp", npmArgs: ["--browser", "chromium"] }

// Custom command
{ command: "bunx", args: ["-y", "@upstash/context7-mcp"] }

// With environment variables
{
  npm: "@some/mcp-server",
  env: { DEBUG: "true", LOG_LEVEL: "verbose" }
}

The npm package will be installed automatically if it is not already installed in your project.

Running the Generator

Run the generator from your project root:

npx @xmcp-dev/cli generate

This reads from src/clients.ts and writes generated clients to src/generated/.

Options:

• -o, --out <path> - Output directory (default: src/generated)
• -c, --clients <path> - Clients file path (default: src/clients.ts)

Generated Output

For each client defined in clients.ts, the CLI generates a client.{name}.ts file containing:

• Zod schemas for each tool's arguments
• Type exports (e.g., GreetArgs)
• Tool metadata objects
• createRemoteToolClient() factory function
• Pre-instantiated client export

An index file (client.index.ts) is always generated with a unified generatedClients object for accessing all clients.

Using Generated Clients

Import generatedClients from the generated index file and call tools directly:

import { InferSchema, type ToolMetadata } from "xmcp";
import { generatedClients } from "../generated/client.index";
import { z } from "zod";

export const schema = {
  libraryName: z.string().describe("The name of the library"),
};

export const metadata: ToolMetadata = {
  name: "get-library-docs",
  description: "Get documentation for a library",
};

export default async function handler({
  libraryName,
}: InferSchema<typeof schema>) {
  const docs = await generatedClients.context.getLibraryDocs({
    context7CompatibleLibraryID: libraryName,
  });
  return (docs.content as any)[0].text;
}

The generated clients provide full autocomplete for all available tools and their arguments.

Example: Browser Navigation

import { InferSchema, type ToolMetadata } from "xmcp";
import { generatedClients } from "../generated/client.index";
import { z } from "zod";

export const schema = {
  url: z.string().describe("The URL to navigate to"),
};

export const metadata: ToolMetadata = {
  name: "browser-navigate",
  description: "Navigate to a URL",
};

export default async function handler({ url }: InferSchema<typeof schema>) {
  await generatedClients.playwright.browserNavigate({ url });
  return `Navigated to: ${url}`;
}

Caveats

• Server must be available — The CLI connects over HTTP or spawns the STDIO package to fetch tool definitions. Ensure the remote server is reachable or the npm package is installed.
• Prefer env for secrets — API keys can be provided as CLI args or via the env map. Prefer env for sensitive values.