---
title: "How to build a custom MCP server in Python | Bombos"
description: "Install the official MCP Python SDK, define tools with @mcp.tool(), run over stdio or Streamable HTTP, test with MCP Inspector, then add OAuth to go remote."
image: "https://bombos.ai/assets/og-en-v2.png"
---

# 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.

*Piet Baudoin · published November 17, 2026 · November 17, 2026*

## 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]"
```

2.  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")
```

3.  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](https://bombos.ai/en/questions/mcp/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](https://bombos.ai/en/questions/mcp/local-vs-remote-mcp-server/), and for the roles involved, [what is an MCP server](https://bombos.ai/en/questions/mcp/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)](https://modelcontextprotocol.io/docs/develop/build-server)
2.  [SDKs (Model Context Protocol)](https://modelcontextprotocol.io/docs/sdk)
3.  [MCP Python SDK documentation](https://py.sdk.modelcontextprotocol.io/)
4.  [Authorization (MCP Python SDK)](https://py.sdk.modelcontextprotocol.io/run/authorization/)
5.  [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
6.  [MCP Python SDK v1 documentation](https://py.sdk.modelcontextprotocol.io/v1/)

## 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](https://bombos.ai/assets/team/piet-klein.jpg)

**Piet Baudoin**You talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe

## More questions about MCP

-   [What is an MCP server?](https://bombos.ai/en/questions/mcp/what-is-an-mcp-server/)
-   [What is an MCP memory server and how does it work?](https://bombos.ai/en/questions/mcp/what-is-an-mcp-memory-server/)
-   [What is the AWS MCP Server and how do you set it up safely?](https://bombos.ai/en/questions/mcp/aws-mcp-server/)
-   [What is the Context7 MCP server, and what does it not do for a team?](https://bombos.ai/en/questions/mcp/context7-mcp-server/)
-   [What is the Datadog MCP server and how do you set it up for a team?](https://bombos.ai/en/questions/mcp/datadog-mcp-server/)
-   [How do I connect an MCP server to Claude, ChatGPT, GitHub Copilot and Grok?](https://bombos.ai/en/questions/mcp/how-to-connect-mcp-to-claude-chatgpt-copilot-and-grok/)
-   [How do I set up the official MCP memory server (server-memory) in Claude Desktop?](https://bombos.ai/en/questions/mcp/how-to-set-up-server-memory-mcp-in-claude/)
-   [Is MCP safe to use in a company, and what controls do we need?](https://bombos.ai/en/questions/mcp/is-mcp-safe-to-use-in-a-company/)

[All questions about MCP →](https://bombos.ai/en/questions/mcp/)


---

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","url":"https://bombos.ai/","logo":"https://bombos.ai/assets/bombos-bee.png","description":"Bombos is the memory layer under every AI your team uses. One shared memory for Claude, ChatGPT, Copilot, Cursor and your own agents, that learns how you work.","sameAs":["https://www.linkedin.com/company/bombos-ai","https://www.youtube.com/@truebombos","https://www.instagram.com/truebombos/","https://bsky.app/profile/bombostrue.bsky.social","https://www.threads.com/@truebombos","https://mastodon.social/@Bombos","https://www.tiktok.com/@truebombos","https://t.me/truebombos","https://www.pinterest.com/truebombos/","https://github.com/bombos-ai","https://linktr.ee/bombos.ai","https://bombosai.substack.com","https://hashnode.com/@bombosai","https://hackernoon.com/u/bombos","https://dev.to/bombos"],"email":"info@bombos.ai","areaServed":["NL","Europe"],"knowsLanguage":["nl","en"],"contactPoint":{"@type":"ContactPoint","email":"info@bombos.ai","contactType":"sales","url":"https://bombos.ai/en/contact/","availableLanguage":["nl","en"]}},{"@type":"WebSite","@id":"https://bombos.ai/#website","name":"Bombos","url":"https://bombos.ai/","inLanguage":["nl-NL","en"],"publisher":{"@id":"https://bombos.ai/#organization"}}]}

{"@context":"https://schema.org","@type":"Article","headline":"How do you build a custom MCP server, for example in Python?","description":"Install the official MCP Python SDK, define tools with @mcp.tool(), run over stdio or Streamable HTTP, test with MCP Inspector, then add OAuth to go remote.","abstract":"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.","datePublished":"2026-11-17T00:00:00.000Z","dateModified":"2026-11-17T00:00:00.000Z","author":{"@type":"Person","name":"Piet Baudoin"},"publisher":{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","logo":{"@type":"ImageObject","url":"https://bombos.ai/assets/bombos-bee.png"}},"image":"https://bombos.ai/assets/og-en-v2.png","mainEntityOfPage":"https://bombos.ai/en/questions/mcp/how-to-build-a-custom-mcp-server/","inLanguage":"en-US","isPartOf":{"@type":"CollectionPage","name":"MCP","url":"https://bombos.ai/en/questions/mcp/"},"citation":[{"@type":"CreativeWork","name":"Build an MCP server (Model Context Protocol)","url":"https://modelcontextprotocol.io/docs/develop/build-server"},{"@type":"CreativeWork","name":"SDKs (Model Context Protocol)","url":"https://modelcontextprotocol.io/docs/sdk"},{"@type":"CreativeWork","name":"MCP Python SDK documentation","url":"https://py.sdk.modelcontextprotocol.io"},{"@type":"CreativeWork","name":"Authorization (MCP Python SDK)","url":"https://py.sdk.modelcontextprotocol.io/run/authorization/"},{"@type":"CreativeWork","name":"MCP Inspector","url":"https://modelcontextprotocol.io/docs/tools/inspector"},{"@type":"CreativeWork","name":"MCP Python SDK v1 documentation","url":"https://py.sdk.modelcontextprotocol.io/v1/"}]}

{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Bombos","item":"https://bombos.ai/en/"},{"@type":"ListItem","position":2,"name":"Questions","item":"https://bombos.ai/en/questions/"},{"@type":"ListItem","position":3,"name":"MCP","item":"https://bombos.ai/en/questions/mcp/"},{"@type":"ListItem","position":4,"name":"How do you build a custom MCP server, for example in Python?","item":"https://bombos.ai/en/questions/mcp/how-to-build-a-custom-mcp-server/"}]}

{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Is FastMCP still the way to build a Python MCP server?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Which languages have an official MCP SDK?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Why does my stdio server break when I print something?","acceptedAnswer":{"@type":"Answer","text":"Over stdio, stdout carries the protocol messages. A print() writes to stdout and corrupts them. Log to stderr instead."}},{"@type":"Question","name":"Does the Python SDK handle login for a remote server?","acceptedAnswer":{"@type":"Answer","text":"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."}}]}
```
