Skip to content
Kitbay

How to build an MCP server

By the Kitbay editorial team ·

To build an MCP server, pick one of the official MCP SDKs, define the tools (and optionally resources and prompts) your server offers, run it over stdio for local use or Streamable HTTP for remote use, and test it with MCP Inspector before connecting it to an AI client. A simple tool server takes a few dozen lines of code.

This guide follows the official MCP documentation, whose tutorial builds a small weather server. If you are new to the terms, start with what an MCP server is.

Step 1: Choose an SDK

The MCP project maintains official SDKs and grades them by feature completeness and maintenance:

Tier Languages
Tier 1 TypeScript, Python, C#, Go, Rust, Ruby
Tier 2 Java
Tier 3 Swift, PHP, Kotlin

Every SDK can expose tools, resources and prompts and supports local and remote transports. SDKs adopt new protocol versions on their own timetable, so check which revision yours supports. The current specification revision is dated 28 July 2026 and makes the protocol stateless: each request carries its own version and capability information. The SDKs handle this for you.

Step 2: Decide what your server offers

MCP servers offer three kinds of building blocks:

Building block Who controls it Use it for
Tools The model decides when to call them Actions and queries: create an issue, search records, convert a file
Resources The application decides what to include Read-only context: a file, a database schema, API documentation
Prompts The user picks them Reusable templates, often shown as slash commands

Most servers start with tools. For each one, write a clear name, a description that tells the model when to use it, and an input schema. The MCP documentation suggests specific names such as calculator_arithmetic rather than a bare calculate. Keep each tool to one operation, and decide early which tools only read and which can change data, because users and clients will want to know.

Step 3: Write the server

The Python version of the official tutorial installs the SDK with uv add "mcp[cli]" and then looks roughly like this:

from mcp.server import MCPServer

mcp = MCPServer("weather")

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get the weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # call the weather service's API here and return readable text
    ...

if __name__ == "__main__":
    mcp.run(transport="stdio")

The SDK reads the type hints and the docstring to build the tool's name, description and input schema. The TypeScript tutorial uses the @modelcontextprotocol/server package with zod for schemas, creates an McpServer and adds tools with registerTool. Other languages follow their own conventions; the tutorial includes Java, Kotlin and C# versions too.

Logging: keep standard output clean

This is the most common early mistake. With stdio, the client and server exchange JSON-RPC messages over standard output, so any extra text printed there breaks the connection. In Python avoid print(); in Node avoid console.log(). Write logs to standard error instead, for example with Python's logging module or console.error().

Step 4: Choose a transport

The specification defines two standard transports:

  • stdio. The client starts your server as a subprocess and exchanges newline-separated messages over its standard input and output. Use it for servers that run on the user's computer. The MCP security guidance recommends stdio for local servers because it limits access to the client that launched them.
  • Streamable HTTP. Your server runs as an independent process with a single endpoint, such as https://example.com/mcp, that accepts POST requests. Each reply is either a JSON object or a short Server-Sent Events stream. Use it for hosted servers that many users connect to by URL.

The older HTTP+SSE transport from 2024 is deprecated; new servers should not use it.

If you choose Streamable HTTP, the specification sets security requirements: validate the Origin header on every request to block DNS rebinding, bind to 127.0.0.1 rather than all interfaces when running locally, and authenticate connections. The MCP documentation recommends OAuth for obtaining tokens, and a server must reject tokens that were not issued for it.

Step 5: Test with MCP Inspector

MCP Inspector is the project's reference tool for testing servers. It needs Node 22.19.0 or newer and runs through npx, with no install:

# browser interface, connected to a local stdio server
npx @modelcontextprotocol/inspector uv --directory /path/to/weather run weather.py

# scriptable command line: list tools and exit
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# a remote server
npx @modelcontextprotocol/inspector --server-url https://example.com/mcp --transport http

It has three modes: a web interface, a CLI for scripts and CI, and a terminal interface (--tui). Use it to check that each tool appears with the right schema, that calls return what you expect, and that errors are clear. Note that it stores secrets in your system keychain when one exists; without one, they go to an unencrypted file unless you set a key.

Step 6: Connect it to a client

For a local server, add the start command to a client. In Claude Desktop, the tutorial adds this to claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/weather", "run", "weather.py"]
    }
  }
}

Use absolute paths, and if the client cannot find uv, give its full path. In Claude Code the equivalent is claude mcp add --transport stdio weather -- uv --directory /ABSOLUTE/PATH/TO/weather run weather.py. For other clients, see how to connect MCP servers to AI clients.

Before you publish

  • Document every tool. State which tools read and which change data, and what credentials the server needs.
  • Ask for the least access. Request narrow API scopes and avoid broad "all access" tokens.
  • Treat inputs as untrusted. Tool arguments come from a model that may have read hostile content.
  • Show install commands in full. Users should see exactly what will run on their machine.
  • Choose a licence and say whether the server is maintained.

Safety note

Servers act on real data. While developing, point yours at test accounts and sample files rather than live systems, and read the MCP project's security guidance on token handling and local servers. Our MCP security questions show what careful users will check.

Related

Developer tooling sits in Kitbay's testing and debugging capabilities, and you can browse existing MCP servers to see how others document their tools. If you mainly want to teach an agent a procedure rather than connect a system, a skill may fit better: see MCP vs skills.

Questions

What language should I use to build an MCP server?
Any language with an official SDK. The MCP project rates TypeScript, Python, C#, Go, Rust and Ruby as Tier 1, Java as Tier 2, and Swift, PHP and Kotlin as Tier 3.
How do I test an MCP server?
Use MCP Inspector, the project's own testing tool. Run npx @modelcontextprotocol/inspector followed by the command that starts your server, then list and call tools in the browser, terminal or CLI.
Why does my stdio MCP server break when I print debug messages?
With the stdio transport, standard output carries the protocol messages, so anything else printed there corrupts them. Send logs to standard error instead.
Do I need to host an MCP server online?
No. A local server that uses stdio runs on the user's computer and is started by their AI client. Host it online with Streamable HTTP only if users should connect by URL.

Sources

More guides