Connect to external MCPs and make their tools yours

xmcp generates typed clients for external MCP servers, so your tools can call them from TypeScript.

Add your clients

You need to create the clients.ts in the /src directory and then add the MCP servers. HTTP entries can forward headers; STDIO entries spawn npm packages.

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",
  },
};

Adding HTTP clients

HTTP map entries accept the following configuration (the map key supplies the default name):

export type HttpClientConfig = {
  type?: "http";
  name?: string;
  url: string;
  headers?: CustomHeaders;
};

Adding STDIO clients

STDIO map entries accept either an npm package or a command configuration:

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

Generate typed clients

Run the generator from your project root. By default it looks for src/clients.ts and writes to src/generated.

npx @xmcp-dev/cli generate

You can also specify the output directory and the clients file path, check out the CLI documentation for more details.

Using the new tools

We will now have the tools from our external clients in the client.index.ts file, now you only have to import and use them.

Web Navigation

// src/tools/browser-navigate.ts
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"),
};

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

// Tool implementation
export default async function handler({ url }: InferSchema<typeof schema>) {
  await generatedClients.playwright.browserNavigate({
    url,
  });

  return `Navigated to: ${url}`;
}

Follow the generated API

Remote servers can change their tool names and schemas. Regenerate after an upstream update and inspect src/generated/client.index.ts before copying a call from an older tutorial. The generated methods and argument types reflect the server you connected to at generation time.

Keep HTTP credentials in environment variables, as in the Context7 configuration above. Handle each returned content type explicitly rather than assuming every result has a text item at index zero. See the client documentation for supported connections.

Build and run the example

If you want to see an example of how to generate clients and use them, you can checkout the external-clients example.

Contributing

Share your feedback and help shape the future of xmcp: GitHub