How do you build a custom MCP server, for example in Python?

Short answer

Use an official MCP SDK: Python, TypeScript, C#, Go, Rust and Ruby are Tier 1. In Python you install mcp[cli], create an MCPServer, turn functions into tools with @mcp.tool(), and run it over stdio for one machine or Streamable HTTP for a team. Test it with the MCP Inspector, and add token verification before anyone else connects to it.

Pick an SDK

You do not write the protocol yourself. The MCP project publishes official SDKs in tiers based on completeness and maintenance:

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

All of them can build servers that expose tools, resources and prompts, over local and remote transports. Pick the language your team already maintains: the server lives as long as the system behind it. Python and TypeScript have the most examples.

A minimal Python server

Use Python 3.11 or higher for the current stable Python SDK v2. The examples below use uv.

  1. Create the project and add the SDK:
uv init crm-server
cd crm-server
uv add "mcp[cli]"
  1. Write server.py. The SDK reads type hints and docstrings to build the tool definition the model sees:
from mcp.server import MCPServer

mcp = MCPServer("crm")

@mcp.tool()
async def find_customer(name: str) -> str:
    """Look up a customer by name and return status and account owner.

    Args:
        name: Company name, or part of it
    """
    # call your CRM's API here
    return f"No customer found for {name}"

if __name__ == "__main__":
    mcp.run(transport="stdio")
  1. Run it with uv run server.py.

The docstring is not decoration. It becomes the tool description, and that is what the model reads when it decides whether to call find_customer. Write it for a colleague who has never seen your CRM.

If you follow an older guide, you will see FastMCP instead of MCPServer. The Python SDK documentation describes v2 as the current stable release line and uses MCPServer; v1 code keeps working if you pin mcp<2.

The one rule that breaks most first servers

Over stdio, the server’s standard output carries the protocol messages. The official tutorial puts it bluntly: never write to stdout, because it corrupts the JSON-RPC messages. A stray print() is enough. Log to stderr, or to a file.

Test before you connect an AI

The MCP Inspector is the reference tool for testing servers. It lists your tools, lets you call them with your own arguments and shows the raw messages:

  • uv run mcp dev server.py starts your Python server with the Inspector.
  • npx @modelcontextprotocol/inspector opens it in the browser for any server, local or remote; --cli gives a scriptable version for CI.

Then add it to a host. For Claude Desktop, put an entry under mcpServers in claude_desktop_config.json with "command": "uv" and the arguments --directory, the absolute path to your project, run and server.py, and restart the app.

Going remote, so the team can use it

A stdio server lives on one machine. To let colleagues and other AI tools reach it, run it over Streamable HTTP:

mcp.run(transport="streamable-http")

The SDK documentation shows this serving the endpoint at http://127.0.0.1:8000/mcp. From there you put it behind HTTPS on a host your team can reach.

Then add sign-in. Authorization in the Python SDK exists only on HTTP transports. The SDK acts as a resource server: it checks tokens, it does not issue them. You:

  1. Choose an authorization server, usually your identity provider (Auth0, Keycloak, Entra or your own).
  2. Implement a TokenVerifier, one async method that takes a token and returns an access token or nothing.
  3. Set AuthSettings with issuer_url (your identity provider), resource_server_url (the public URL of your MCP endpoint) and required_scopes.

The common misunderstanding: wrap the whole API

The tempting first version exposes every API endpoint as a tool. That gives the model dozens of near-identical choices and a lot of write power. Better servers expose a handful of tools shaped around tasks (“find customer”, “log a call”), make writes explicit, and put read-only reference material in resources: data the application reads for context, rather than actions the model takes. Start read-only, and add write tools one at a time.

What this means for a team

A custom server is the cleanest way to give every MCP-capable tool your team uses the same access to an internal system: one server, one place for permissions, and every Claude, ChatGPT or Cursor user sees the same tools. Decide early who maintains it, because it breaks when the API behind it changes. Before you build, check whether the vendor already offers one: see where to find trustworthy MCP servers. For the trade-offs of running it locally or as a hosted service, read local vs remote MCP servers, and for the roles involved, what is an MCP server.

Where Bombos fits

A custom server gives your AI tools access to a system. It does not give them memory of how your team works. Bombos is a plugin that adds that layer for every AI tool you use (Claude, Claude Code, ChatGPT, Copilot, Grok, Codex, Cursor, your own agents): shared team knowledge, rules the AI learned from your corrections, and what already sits in mail, documents and repos, with a trail of what each answer rests on. It runs in our cloud or on your own server, and one person can try it first with their own agents.

Related questions

Is FastMCP still the way to build a Python MCP server?

The official Python SDK documentation for v2, the current stable line, uses the MCPServer class from mcp.server. Older tutorials and the v1 SDK use FastMCP; pin mcp<2 if you need to stay on v1.

Which languages have an official MCP SDK?

Tier 1: TypeScript, Python, C#, Go, Rust and Ruby. Tier 2: Java. Tier 3: Swift, PHP and Kotlin. The tier reflects feature completeness and maintenance commitment.

Why does my stdio server break when I print something?

Over stdio, stdout carries the protocol messages. A print() writes to stdout and corrupts them. Log to stderr instead.

Does the Python SDK handle login for a remote server?

It verifies tokens but does not issue them. You implement a TokenVerifier and point to your identity provider, such as Auth0, Keycloak or Entra, as the authorization server.

Sources

  1. Build an MCP server (Model Context Protocol)
  2. SDKs (Model Context Protocol)
  3. MCP Python SDK documentation
  4. Authorization (MCP Python SDK)
  5. MCP Inspector
  6. MCP Python SDK v1 documentation
The first half hour · free

What does your AI forget?

  1. 01You tell us which AI you use and where it keeps starting over.
  2. 02We show what a shared memory changes there, on your own examples.
  3. 03You keep the plan, with or without Bombos.
Piet Baudoin
Piet BaudoinYou talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe
We reply the same working day.