mcp-server-kit

Shared plumbing for Python MCP servers built on the official SDK's FastMCP (mcp.server.fastmcp). It covers the parts every server ends up copying:

Install

uv add mcp-server-kit        # or: pip install mcp-server-kit

It pins mcp>=1,<2, so the SDK range lives in one place for every server built on the kit.

Use

import logging
import os

from mcp.server.fastmcp import FastMCP
from mcp_server_kit import offload_sync_tools, serve

mcp = FastMCP("example", instructions="...", stateless_http=True, json_response=True)
offload_sync_tools(mcp, logger_name="example_mcp.requests")   # before the first @mcp.tool()


@mcp.tool()
def lookup(query: str) -> str:
    """A blocking call is fine here: it runs in a worker thread."""
    ...


def main() -> None:
    logging.basicConfig(level=logging.INFO)
    serve(mcp, port=8000, bearer_token=os.environ.get("MCP_BEARER_TOKEN", ""))

lookup stays a plain function, so tests and other tools can call it directly.

To give every tool the same annotations unless it passes its own: offload_sync_tools(mcp, logger_name=..., default_annotations=ToolAnnotations(readOnlyHint=True)).

Healthcheck module for a container (HealthCmd=python -m example_mcp.healthcheck):

from mcp_server_kit.healthcheck import probe

def main() -> None:
    probe(8000)

if __name__ == "__main__":
    main()

Shared non-thread-safe clients (e.g. cached httplib2 objects) need a lock in the server. Thread-safe ones (httpx.Client, requests.Session) don't.

Develop

uv sync --extra test
uv run pytest -q

MIT licensed.