MCP Client Guide: What It Is, Top Clients and How to Build One

An MCP client is the connector inside an AI application that holds a connection to exactly one MCP server. It sends that server's requests (list tools, call a tool, read a resource), and it passes results back to the app. The application that runs the model and the UI is called the host. A host such as Claude Code, Cursor or VS Code creates one client for every server you configure. People often say "MCP client" when they mean the whole app, and that's fine in everyday speech, but the difference matters once you build one.

This guide covers what a client does on the wire, which clients support what in October 2026, and how to write a minimal client with the official TypeScript and Python SDKs. If you need the protocol basics first, read What is MCP?. For the message-by-message flow, see How does MCP work?.

Host vs client vs server

The MCP architecture spec names three roles:

So if you connect three servers to Cursor, you have one host and three clients. Keeping one client per server is part of the security model: a server never sees the full conversation, and it can't see into other servers. The host decides what crosses those boundaries. (For the server side of the picture, see What is an MCP server?.)

What an MCP client actually does

Under the current spec revision, 2026-07-28, MCP is stateless. That changes the client's job compared with older tutorials, which open with an initialize handshake. A modern client:

1. Attaches metadata to every request. Each JSON-RPC request carries _meta with io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities (both required), and usually io.modelcontextprotocol/clientInfo. On Streamable HTTP, the client also sends a matching MCP-Protocol-Version header (spec).
2. Optionally discovers the server. server/discover returns supported versions, capabilities and server instructions in one call. Calling it is optional, but it is the recommended probe on stdio when the server might be an older, handshake-based one.
3. Lists and calls primitives. It sends tools/list, resources/list and prompts/list, hands the tool definitions to the model, and sends tools/call when the model picks a tool.
4. Answers input requests. When a server needs something from the user, it no longer sends a request of its own. It returns an InputRequiredResult (resultType: "input_required"), for example an elicitation form. The client shows the form, then retries the original request with inputResponses. This pattern is called Multi Round-Trip Requests.
5. Listens for changes. To learn when a tool list changes or a resource updates, the client opens a long-lived subscriptions/listen request and opts in to specific notification types.
6. Handles auth. For remote HTTP servers, the client runs the OAuth flow in the authorization spec. Stdio servers take credentials from environment variables instead. Our MCP authentication guide covers the details.

Roots, sampling and logging still work, but the 2026-07-28 revision marks them deprecated, so a new client doesn't need to add them.

Major MCP clients compared

Every cell below comes from the vendor's current docs. "Not documented" means we could not find it in the official docs, not that the feature is missing.

Some notes from the docs:

• Claude Code stores servers in three scopes (local, project, user). It asks for prompts/list and resources/list during discovery, and it refreshes lists when servers send list-changed notifications (docs). Setup is in our Claude Code MCP guide.
• Claude Desktop reads local servers from ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Remote servers are added as Custom Connectors under Settings → Connectors (docs). See Claude Desktop MCP setup.
• Cursor has one of the broadest feature lists, with roots, elicitation and MCP Apps all marked supported (docs). See Cursor MCP setup.
• VS Code now prefers a workspace .mcp.json with a mcpServers key. The older .vscode/mcp.json, which uses a servers key, is deprecated for new servers. Prompts appear as /<server>.<prompt> (docs). See VS Code MCP setup.
• ChatGPT connects only to remote servers, through Plugins on the web (docs). See ChatGPT MCP setup.
• Codex uses one config.toml across the CLI, the IDE extension and Codex in the ChatGPT desktop app. See Codex MCP setup.

For the full list, including Windsurf, Zed, Cline, Goose and others, browse the MCP.so clients directory.

Build a minimal MCP client

You only need to write a client if you're building your own host, such as an agent, a chatbot, a test harness or a gateway. Both Tier 1 SDKs moved to v2 in 2026 and support the stateless revision.

TypeScript (@modelcontextprotocol/client v2)

npm install @modelcontextprotocol/client

import {
  Client,
  StreamableHTTPClientTransport,
} from '@modelcontextprotocol/client';

const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  { versionNegotiation: { mode: 'auto' } }
);

await client.connect(
  new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'))
);
console.log(client.getProtocolEra()); // 'modern' or 'legacy'

const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

const result = await client.callTool({
  name: 'greet',
  arguments: { name: 'Ada' },
});
if (result.isError) {
  console.error('Tool failed:', result.content);
} else {
  console.log(result.content);
}

await client.close();

Three details from the SDK docs are easy to miss:

• versionNegotiation. Without it, connect() runs the legacy 2025 initialize handshake. mode: 'auto' probes with server/discover and falls back to the handshake if the server is older. mode: { pin: '2026-07-28' } refuses to fall back.
• Tool errors come back as results. A tool that fails returns isError: true instead of throwing, so check it before you trust content. Only protocol failures, such as an unknown tool or a timeout, throw.
• listTools() follows every page. It walks pagination for you, up to listMaxPages, which defaults to 64.

To launch a local server instead, change only the transport:

import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

await client.connect(
  new StdioClientTransport({ command: 'node', args: ['server.js'] })
);

To accept elicitation, declare the capability in the constructor (capabilities: { elicitation: { form: {} } }) and register a handler with client.setRequestHandler('elicitation/create', ...). The SDK takes care of the MRTR retry.

Python (mcp v2)

uv add "mcp[cli]"

import asyncio

from mcp import Client


async def main() -> None:
    async with Client("http://localhost:8000/mcp") as client:
        tools = await client.list_tools()
        print([t.name for t in tools.tools])

        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(result.structured_content)


asyncio.run(main())

When you pass a URL, Client uses Streamable HTTP. For a local server, pass a stdio transport instead: Client(stdio_client(StdioServerParameters(command="python", args=["server.py"]))), imported from mcp and mcp.client.stdio (Python SDK). The async with block covers the whole lifecycle. Entering it connects and agrees on a protocol version, and leaving it shuts everything down.

Wire it to a model

A useful client turns MCP tool definitions into your LLM's tool format. You map name, description and inputSchema, send the model's tool calls through callTool, and add the results to the conversation. The official build-a-client tutorial shows the full loop with the Anthropic SDK. Before you point your client at real servers, test it with the MCP Inspector.

How to choose an MCP client

• Coding agent in the terminal: Claude Code or Codex. Both have CLI commands for adding servers and OAuth login.
• IDE: Cursor or VS Code. Cursor documents more of the optional features (roots, elicitation, Apps). VS Code fits teams that are already on Copilot.
• Chat for non-developers: claude.ai or ChatGPT, with remote servers only. Pick servers that offer a hosted HTTPS endpoint, such as Notion or Sentry.
• Your own product: use an SDK client, turn on versionNegotiation: 'auto' (or the Python v2 Client) so you work with both modern and legacy servers, and follow MCP security best practices. In particular, show tool calls to the user and ask before running anything with side effects.

Feature support changes from release to release. Before you rely on resources, prompts or elicitation, confirm that your target client documents them. Otherwise, expose the same capability as a tool, because every client supports tools.

Next steps

Once you've picked a client, give it something to connect to. Browse thousands of servers in the MCP.so server directory, compare apps in the clients directory, or start with our list of the best MCP servers.

Want to run everything on your own hardware? See how to use MCP tools with local Ollama models.