Skip to content
Back to blog

How to call an MCP server from TypeScript

Connect to any MCP server from Node.js: list its tools, call one, read structured results, answer its questions, and cancel long calls, using xmcp's managed client over HTTP or STDIO.

To call an MCP server from TypeScript, open a connection, call listTools() or callTool(), and close the connection. With xmcp that is one function: withClient from xmcp/client connects over HTTP or STDIO, runs your callback, and closes the connection even when the callback throws.

TypeScript

The client works with any MCP server, not only ones built with xmcp. This guide uses three scripts from the repository's examples.

Which way of calling a server should I use?

xmcp gives you three, for different jobs:

OptionUse it whenYou write
Managed client (xmcp/client)A script, backend, or agent talks to a server at runtimecreateClient or withClient
CLI (@xmcp-dev/cli)You want to inspect or call a server from the terminalNothing
Generated typed clientsTools in your xmcp server call another MCP serverA src/clients.ts entry

This guide covers the first two. For generated clients, see Connect to external MCPs and make their tools yours.

How do I connect over HTTP?

Pass a definition with type: "http" and the server's URL. withClient returns whatever your callback returns:

examples/structured-output/client.mjs

The client is the connected MCP SDK client, with listTools, callTool, readResource, getPrompt, and the rest. The connection negotiates the protocol version on its own: it speaks 2026-07-28 to servers that support it and falls back to the initialize handshake for older ones.

A tool that declares an outputSchema returns its data in structuredContent, so there is no text to parse. See MCP structured output.

How do I connect to a local STDIO server?

Use type: "stdio" with the command that starts the server. The client spawns the process and waits for it to exit when the connection closes:

TypeScript

STDIO definitions also accept env, cwd, and stderr. The server's stderr is inherited by default, so its logs appear in your terminal.

When should I use createClient instead?

When the connection should outlive one operation. createClient returns the connected client and leaves closing it to you:

TypeScript

Prefer withClient for one-off work. It cannot leak a connection or a child process.

How do I handle errors?

There are two kinds, and they arrive differently:

What went wrongHow it arrives
The tool ran and failedA result with isError: true
The arguments failed validationA result with isError: true
The tool does not existThe promise rejects with a protocol error
The server cannot be reachedThe promise rejects

Check result.isError before using a result. The error text is in result.content, written for the model to read and recover from.

How do I answer a question from the server?

Some tools pause to ask the user something. Register a handler and the client answers on its own:

examples/human-in-the-loop/client.mjs

On a 2026-07-28 connection the server returns an input_required result; the SDK passes the embedded question to your handler and retries the call with the answer. Your code sees one callTool that resolves with the final result.

Handlers exist for elicitation, sampling, and roots. The client advertises a capability only when you register its handler, so a server never asks for something the client cannot do. See Human-in-the-loop MCP tools for the server side.

How do I cancel a call or set a timeout?

Pass an AbortSignal in the request options, and bound connection setup with connect:

TypeScript

Call controller.abort() from your own cancel action. On 2026-07-28 connections and on STDIO the cancellation reaches the server's handler. Legacy stateless HTTP cannot route a cancellation to an earlier request.

How do I call a server without writing code?

Use the CLI. It prints the complete MCP result as JSON:

Shell

inspect shows the server's identity, negotiated protocol version, and capabilities. list returns its tools, prompts, resources, and resource templates. call checks the arguments against the tool's schema, calls it, and exits with 1 when the tool returns an error, which makes it usable in scripts and CI.

Run the examples

Use Node.js 22.12 or later and pnpm. From a checkout of the xmcp repository:

Shell

In another terminal:

Shell

It prints one line per forecast day. The external clients example has a script that lists a server's tools, and the human-in-the-loop example has the handler script above.

Common questions

Does the xmcp client work with servers not built with xmcp?

Yes. It is an MCP client. It connects to any server that speaks MCP over Streamable HTTP or STDIO.

Does it run in the browser or on Cloudflare Workers?

xmcp/client is a Node.js entry. It can spawn STDIO processes, which needs Node.js.

How do I send an API key or bearer token?

Add headers to an HTTP definition. Headers accept static values and references to environment variables, so secrets stay out of source.

Do I need to call initialize first?

No. The connection negotiates the protocol for you: a server/discover probe for 2026-07-28 servers, with a fallback to the initialize handshake. Pass versionNegotiation: { mode: "legacy" } to force the older handshake.

Is the client deprecated along with sampling and roots?

No. MCP 2026-07-28 deprecates the Sampling and Roots features, not clients. The sampling and roots handlers remain for servers that still use those features during the deprecation window.

Next steps

One framework to rule them all