Building an MCP Server

When a client connects it runs an initialize handshake, exchanges capabilities, then calls tools/list to discover your tools and tools/call to invoke one. Your job is to describe those tools precisely and implement what happens on a call.

A minimal server

The official Python mcp SDK, in its low-level API, makes each part explicit:

import asyncio
from mcp.server.lowlevel import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

server = Server("math-server", version="1.0.0")

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [Tool(
        name="add",
        description="Add two numbers and return their sum.",
        inputSchema={
            "type": "object",
            "properties": {"a": {"type": "number"}, "b": {"type": "number"}},
            "required": ["a", "b"],
        },
    )]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    total = arguments["a"] + arguments["b"]
    return [TextContent(type="text", text=str(total))]

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write, server.create_initialization_options())

asyncio.run(main())

list_tools returns the contract; call_tool is the handler that receives already-parsed arguments, computes $a + b$, and returns a list of content blocks. create_initialization_options() packages the server identity and capabilities for the handshake, and stdio_server() wires standard input and output as the transport, exactly what a local client launches and speaks to.

Build it step by step

1. 1Define the serverInstantiate it with a clear name and version so clients can identify and log it.
2. 2Declare capabilitiesRegistering tool handlers turns on the tools capability; create_initialization_options() advertises it during initialize.
3. 3Register the tool and schemaReturn a Tool with a precise description and a strict JSON Schema inputSchema that constrains every field.
4. 4Implement the handlerValidate the arguments, do the work, and return content blocks; surface failures as an error result rather than a crash.
5. 5Connect a transportUse stdio for a local client launched as a subprocess; switch to streamable HTTP for a remote service.
6. 6Test with a client or inspectorRun the MCP Inspector or point an agent at the server to list and call the tool end to end.

Why descriptions and schemas decide accuracy

The model never sees your code, only the tool name, description, and inputSchema. Those three fields are the prompt that determines whether the tool is chosen and called with correct arguments. A precise description and a strict schema, where a and b are typed as numbers and marked required, remove ambiguity; vague text and loose schemas invite wrong arguments or skipped calls.

Choosing a transport

Further reading

• Build an MCP server, quickstart
• Official Python SDK
• Official TypeScript SDK
• MCP Inspector