OpenWikimodelcontextprotocol/typescript-sdk

Connect to a Real Host

Purpose and Scope

This page explains how to move the getting-started weather MCP server from a local terminal exercise into a real host application. A host is the end-user application that contains the model and decides when to use MCP capabilities, such as VS Code with Copilot, Claude Code, or Cursor. The important shift is that you stop manually driving the server and instead give the host a launch command. The host starts the same server process, connects to its standard input and output, lists its tools, and lets the model choose when to call them.

Sources: docs/get-started/real-host.md

The documented tutorial is deliberately narrow: it assumes the weather server already exists and exposes the get-alerts tool from the first server guide. There is no new server implementation to write on this page. The same npx tsx src/index.ts command remains the integration boundary, and every host-specific setup only changes where that command is registered. That framing matters because host integration problems are usually launch, working-directory, trust, or logging problems rather than SDK API problems. If the server runs by hand but not in the host, inspect the host configuration first.

Sources: docs/get-started/real-host.md

Relevant Source Files

  • docs/get-started/real-host.md — first-party tutorial for registering the weather server in real MCP hosts, approving a Copilot tool call, tracing the tools/call round trip, and reusing the same stdio launch command across hosts.
  • docs/.vitepress/nav.ts — places “Plug into a real host” in the Get started sidebar immediately after “Build a server,” which shows this page is the next step after creating a runnable server.
  • docs/.vitepress/llms.ts — generates LLM-facing markdown renditions and indexes guide pages in sidebar order, so this tutorial is part of the public docs surface consumed by agents.
  • docs/.vitepress/theme/index.ts — wires the VitePress theme and banner for the current docs site that publishes this guide.
  • docs/v1/.vitepress/theme/index.ts — shows the v1 docs theme shares the same custom styling while keeping a separate docs tree, which helps distinguish current v2 guidance from v1 material.
  • docs/_meta/CONVENTIONS.md — defines the docs style rules for tutorial pages, including code-first flow, imperative micro-steps, observable results, and recap structure.

Core Primitives

The primitive in this guide is a stdio-launched MCP server. In practical terms, the host starts a child process, writes protocol messages to the child process standard input, and reads protocol messages from standard output. The tutorial’s server entry uses serveStdio(createServer) and writes its human-readable startup message with console.error. That separation is not cosmetic: stdout is the protocol channel, so a stray console.log can corrupt the message stream and make the host drop the connection. Treat stderr as the only safe place for process diagnostics in this flow.

Sources: docs/get-started/real-host.md

The second primitive is the host’s MCP client. In VS Code, Copilot is the model-facing feature, but the MCP client inside the host sends the actual tools/call request to the server. The model sees tool names, descriptions, and JSON Schema derived from the server registration; it does not need the user prompt to name the tool directly. When the user asks about active weather alerts in Texas, the model can infer that get-alerts is relevant, provide a two-letter state argument, and wait for the host’s approval before the server handler runs.

Sources: docs/get-started/real-host.md

Host Registration Flow

Start with the launch command the tutorial already uses from the weather project root. The command is stable across hosts: npx is the executable, and tsx plus src/index.ts are the arguments. For VS Code, create .vscode/mcp.json under the project root and add a server entry named weather with type set to stdio. VS Code launches the command from the workspace root, asks the user to trust the new server, and then exposes it through the Command Palette via MCP server listing.

Sources: docs/get-started/real-host.md

{
  "servers": {
    "weather": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "src/index.ts"]
    }
  }
}

Once VS Code reports the server as running, open Copilot Chat and switch the mode selector to Agent mode. The tutorial calls out Agent mode because it is the Copilot mode that invokes tools. Ask a natural-language question such as “What are the active weather alerts in Texas?” and approve the proposed get-alerts call when Copilot shows it. The visible result is produced from the text content returned by the server handler, not from a hard-coded host integration. The host provides the orchestration; the server remains the source of the tool behavior.

Sources: docs/get-started/real-host.md

Claude Code uses the same process contract with different registration syntax. From the project root, run the CLI command that adds an MCP server named weather, then place the launch command after --. Inside a Claude Code session in that directory, /mcp shows the connected server and lists get-alerts under it. Cursor follows the same command-and-arguments pattern through .cursor/mcp.json; the supplied source shows the file path and the mcpServers wrapper before the snippet ends. The key invariant is that the server command does not change between hosts.

Sources: docs/get-started/real-host.md

claude mcp add weather -- npx tsx src/index.ts

System-to-Code Mapping

The docs navigation makes this page part of the Get started path, directly after the first server tutorial and before the first client tutorial. That order is significant for readers: the page teaches what happens when an existing server is consumed by a real application before asking them to build an SDK client manually. The LLM-rendition generator mirrors the guide sidebar order into llms.txt, page-specific markdown renditions, and a concatenated guide file, which means this tutorial is also exposed as structured product documentation for agentic readers.

Sources: docs/.vitepress/nav.ts, docs/.vitepress/llms.ts

The VitePress theme files do not define MCP behavior, but they show how the current and v1 documentation sites are presented. The current docs theme extends the default VitePress theme and injects a banner at the top of the layout. The v1 theme imports shared custom CSS from the current docs tree instead of duplicating it. For this page, the practical signal is that host-integration guidance belongs to the current v2 guide site, while older v1 documentation remains visually related but separated in its own docs tree.

Sources: docs/.vitepress/theme/index.ts, docs/v1/.vitepress/theme/index.ts

The conventions file explains why the underlying tutorial reads as a sequence of imperative micro-steps rather than a broad conceptual essay. It requires tutorial pages to put code early, keep main-flow paragraphs short, define terms inline, move caveats into warning or info containers, and end with a recap. Those rules align with the real-host task: the reader needs a working configuration, an observable running server, and a clear warning about stdout. When extending this guide, preserve that task flow and avoid adding new server code unless the launch contract changes.

Sources: docs/_meta/CONVENTIONS.md

Execution Details and Troubleshooting Signals

When a host cannot connect, verify the same command succeeds from the project root before editing SDK code. A host normally inherits or sets a working directory, and the VS Code tutorial explicitly says it runs the command from the workspace root. Confirm that src/index.ts ends in the stdio serving entry, that the process writes protocol messages only to stdout, and that logs go to stderr. Then check host-specific requirements: VS Code needs version 1.99 or later, the GitHub Copilot extension, a signed-in account, trust approval, and Agent mode for tool calls.

Sources: docs/get-started/real-host.md

The round trip is the best mental model for debugging behavior after connection succeeds. The host sends the user’s question and tool metadata to the model, the model emits a tool call, the host sends tools/call to the server, the SDK validates the selected arguments against the registered input schema, the handler returns content, and the model writes the final answer from that content. If the wrong tool is chosen, improve the tool name, description, or schema in the server guide. If validation fails, inspect the input schema and the arguments the host proposes.

Sources: docs/get-started/real-host.md

Next Steps

Use this page when your server already works locally and you need a real host to launch it. Continue to the first-client guide when you want to write your own MCP client instead of relying on VS Code, Claude Code, or Cursor as the host. Read the stdio serving page when you need deeper transport behavior, and read the tools page when the model can see your server but chooses the wrong capability or supplies invalid arguments. For production-style deployments, move from local stdio host registration to the serving, authorization, and sessions guides.

Sources: docs/get-started/real-host.md, docs/.vitepress/nav.ts

Ask a question...