How to Build and Connect a Custom MCP Server with Python SDK v2 (2026)
MCP & Agents(Updated )

How to Build and Connect a Custom MCP Server with Python SDK v2 (2026)

Build a narrow MCP server

A local MCP server can expose a small capability to a compatible host without publishing an HTTP service. The useful starting point is a tool with a clear purpose and limited authority: for example, report aggregate capacity for one fixed filesystem, without accepting arbitrary paths or shell commands.

Correction: An earlier version named an exact SDK release and reported a successful STDIO smoke test without verifiable release or execution evidence. Those claims have been removed. The configuration and validation steps below are guidance, not a record of a completed deployment.

The official Python SDK documentation describes v2 as its current stable line, requires Python 3.11 or newer, and shows MCPServer with a decorated tool. These live documents do not establish which releases or APIs were available on this article’s original publication date. Before implementing anything, check documentation and package records for the exact release you choose.

1. Choose and verify the SDK release

Use this decision path before writing server code:

  • Starting a new v2 server? Identify an official mcp package release, confirm its Python requirements and inspect that release’s documentation or source for the APIs you intend to use. Pin the exact version in your environment and record the package artifact and dependency lock.
  • Maintaining a v1 server? The v1 maintenance-line documentation advises constraining mcp below 2 to avoid an unintended major-version upgrade. It shows FastMCP imported from mcp.server.fastmcp; the v2 documentation instead shows MCPServer imported from mcp.server. Treat migration as an API change and consult the migration material for your selected releases.
  • Unsure which API your environment contains? Stop before copying examples. Check the installed distribution, interpreter and release-specific reference together. Similar class or package names do not establish interchangeability.

The supplied documentation does not establish a particular v2 patch release or verify an installation of one. An exact install command here would therefore give a false impression of version-specific support. Use your organization’s approved package source and the chosen release’s official installation instructions, then record the resolved version and dependencies. The SDK documentation says the optional cli extra provides the development command; it is not a substitute for confirming the API of a pinned release.

2. Design the tool before connecting it

For a fixed-filesystem capacity tool, specify the contract first:

  1. Input: none. The server selects one approved filesystem rather than accepting a caller-provided path.
  2. Output: aggregate total, used and available capacity, or a bounded error if the check fails.
  3. Authority: read only, under a dedicated account with only the permissions needed for the check.
  4. Disclosure: capacity and errors may reveal operational information. Decide which clients may receive them and avoid returning host paths, secrets or unnecessary diagnostics.

In the documented v2 pattern, a server instance registers a Python function with @mcp.tool(). The SDK example uses type hints to describe tool inputs and a docstring to describe the operation. Those descriptions help a client present the tool; they do not authorize a caller or constrain the process’s operating-system permissions.

Use the API reference and examples for your pinned release to implement and register the function. Check how that release represents errors and results, and test failure cases such as an inaccessible filesystem. Avoid a general-purpose shell tool: it would grant substantially broader authority than this task needs.

3. Select a transport and connect the host

The server execution guide describes this transport choice:

  • Local host launching a child process: use STDIO when supported by both the chosen SDK release and host. The host writes requests to the child’s stdin and reads responses from stdout; no listening port is needed.
  • A service that must be reached over a network: evaluate Streamable HTTP and establish authentication, authorization, transport security and deployment controls before exposing it.
  • A client requiring legacy SSE: check compatibility explicitly. The guide says Streamable HTTP superseded SSE in the 2025-03-26 protocol revision and recommends SSE only for older clients.

For the documented v2 behavior, run() blocks for the server’s lifetime and defaults to STDIO. A process waiting for a host is therefore not, by itself, evidence of a hang. Put the run call behind the Python main guard so that importing the module for inspection or testing does not start the server.

STDIO also makes stdout part of the protocol boundary. The current run guide describes diverting flushed output during serving, but warns that output before serving starts and buffered output at exit can still reach the wire. Configure diagnostics to use stderr and check wrappers and import-time code as well as the tool itself. Verify this behavior against the pinned release; do not assume every version handles output identically.

Host registration is product- and version-specific. Consult the host’s own documentation for its supported registration mechanism, executable path, arguments, working directory and environment. Point it at the isolated interpreter containing the pinned SDK and at the intended server file. Do not assume a configuration path or manifest accepted by one client applies to another.

4. Validate in stages

Perform these checks in an isolated environment before granting a host broader access. Record the exact Python, SDK, dependencies, host and protocol versions alongside dated logs, with sensitive material removed.

  1. Import and registration: Confirm that the server module loads under the intended interpreter and that the expected tool is registered. If import fails, resolve the environment or API mismatch before debugging transport.
  2. Handshake: Start the server through a compatible test client using STDIO. Confirm initialization completes and inspect stderr separately from protocol traffic. If the connection closes, check executable paths, startup errors and unexpected stdout bytes.
  3. Discovery and call: List tools, compare the name and input schema with the contract, then invoke the harmless capacity check. Confirm the result describes the intended filesystem and that failure responses do not disclose sensitive details.
  4. Host integration: Repeat discovery and the bounded call in the actual host. Inspect its approval and auto-approval settings rather than assuming each call receives human review.
  5. Upgrade: When the SDK or host changes, repeat the checks against the new pinned versions. A successful SDK-to-SDK exchange alone would not establish compatibility with every host.

The official documentation describes an Inspector workflow and notes that it needs Node.js and npx on the path. Use the instructions for the pinned release and record what actually happened; the existence of a documented workflow is not evidence that this article ran it.

5. Keep the authority boundary visible

Run the server with least privilege, keep credentials out of published configuration, and restrict who can start or connect to it. Validate inputs for any future tools, authorize state-changing operations separately, and enforce timeouts and resource budgets outside the model. A read-only tool can still disclose data; review both successful responses and errors.

For HTTP deployment, a working local STDIO test does not validate network authentication, exposure, session handling or transport security. Review those controls for the chosen release and deployment environment before opening access.

Primary sources

Validation boundary: No versioned execution receipt was supplied for installation, registration, handshake, tool invocation or client deployment. This article reports no successful test. Source excerpts reviewed November 13, 2026; their current descriptions do not establish historical availability or behavior for a particular pinned release.

BC

Written by B. Cho

Systems & AI Infrastructure Engineer

Specializing in GPU inference engines (vLLM, SGLang, Ollama), CUDA memory allocation, and Model Context Protocol (MCP) infrastructure on Linux workstations.