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
- Build an MCP server (MCP docs)checked Nov 14, 2026
- SDKs (MCP docs)checked Nov 14, 2026
- Understanding MCP servers (MCP docs)checked Nov 14, 2026
- MCP architecture overviewchecked Nov 14, 2026
- Transports (MCP specification)checked Nov 14, 2026
- Streamable HTTP (MCP specification)checked Nov 14, 2026
- MCP Inspector (MCP docs)checked Nov 14, 2026
- Security considerations (MCP docs)checked Nov 14, 2026