pymcp-kit 0.3.0

A capability-first MCP server toolkit for FastAPI with Streamable HTTP and stdio transport

PyMCP Kit

Documentation | Quick Start | Tasks | Security | Middleware

PyMCP Kit is a capability-first MCP server toolkit for FastAPI. It keeps the built-in transport surface small, supports Streamable HTTP and stdio, and ships app-scoped registries, roots, tasks, optional auth hooks, OAuth protected-resource metadata, and opt-in draft MCP support without pulling in a larger framework.

Quick Start

Install from PyPI:

pip install pymcp-kit

For local development from this repo:

pip install -e .

Register tools, prompts, and resources, then build an app:

from pymcp import (
    CapabilitySettings,
    ServerSettings,
    create_app,
    prompt_registry,
    resource_registry,
    tool_registry,
)


@tool_registry.register
def add(a: float, b: float) -> str:
    return str(a + b)


@prompt_registry.register(description="Create a release summary prompt.")
def summarize_release(topic: str) -> str:
    return f"Summarize the release impact for {topic}."


@resource_registry.register(
    uri="memo://release-plan",
    name="release_plan",
    description="Latest release checklist",
    mime_type="text/markdown",
)
def release_plan() -> str:
    return "# Release Plan\n- freeze API\n- tag build\n"


@resource_registry.register_template(
    uri_template="note://{topic}",
    name="topic_note",
    description="Parameterized note resource keyed by topic.",
)
def topic_note(topic: str) -> str:
    return f"Notes for topic: {topic}"


app = create_app(
    server_settings=ServerSettings(
        name="demo-server",
        version="0.1.0",
        capabilities=CapabilitySettings(
            advertise_empty_prompts=False,
            advertise_empty_resources=False,
        ),
    )
)

The HTTP transport is mounted at /mcp. For local-process integrations, use run_stdio_server(app).

Stable MCP revisions are enabled by default. To build against the draft stateless revision, opt in explicitly:

app = create_app(protocol_mode="draft")  # 2026-07-28 only
app = create_app(protocol_mode="dual")   # draft plus stable clients

Draft extension capabilities are advertised under the spec extensions object. Built-in task support becomes extensions["io.modelcontextprotocol/tasks"] for the draft revision, and additional namespaced extensions can be supplied with CapabilitySettings(extensions={...}).

Official extension capability advertisement is opt-in:

from pymcp import CapabilitySettings, ServerSettings, create_app

app = create_app(
    server_settings=ServerSettings(
        protocol_mode="draft",
        capabilities=CapabilitySettings(
            mcp_apps_enabled=True,
            oauth_client_credentials_enabled=True,
            enterprise_managed_authorization_enabled=True,
        ),
    )
)

Hosted documentation is built from docs/ with MkDocs Material and published to GitHub Pages.

Features

• Streamable HTTP transport for networked MCP servers
• Stdio transport for local-process MCP hosts
• Opt-in draft 2026-07-28 stateless protocol support with server/discover and namespaced extensions
• Tool, prompt, and resource registries, including parameterized resource templates
• Roots, resource subscriptions, and app-scoped session lifecycle
• Task-aware tool execution with progress, cancellation, and result polling
• Optional authentication and authorization hooks with OAuth protected-resource metadata discovery
• Capability advertising through CapabilitySettings
• FastAPI middleware integration through MiddlewareConfig
• Small surface area focused on practical MCP server builds

Supported MCP Methods

Server-side JSON-RPC methods and notifications implemented by pymcp-kit:

Lifecycle

• initialize
• ping
• notifications/initialized
• notifications/cancelled
• server/discover (draft 2026-07-28, when protocol_mode="draft" or "dual" is enabled)

Tools

• tools/list (cursor pagination)
• tools/call

Prompts

• prompts/list (cursor pagination)
• prompts/get

Resources

• resources/list (cursor pagination)
• resources/templates/list (cursor pagination)
• resources/read
• resources/subscribe
• resources/unsubscribe
• notifications/resources/updated (server → client)
• notifications/resources/list_changed (server → client, when enabled)

Completions

• completion/complete (when completions_enabled is set)

Tasks

• tasks/list (cursor pagination)
• tasks/get
• tasks/cancel
• tasks/result
• notifications/tasks/status (server → client)
• notifications/progress (server → client)

Client capabilities (server-initiated helpers)

These are not inbound server handlers; the toolkit sends requests or notifications to the client when the client advertises the capability:

• roots/list via request_roots_list()
• notifications/roots/list_changed (client → server notification)
• elicitation/create via request_elicitation()
• sampling/createMessage via request_sampling()
• notifications/message via send_log_message()

List operations support optional cursor / nextCursor pagination. Page size is controlled by CapabilitySettings.list_page_size (default 50).

See Runtime Surface for protocol versions, HTTP endpoints, and capability settings.

Example Server

Run the bundled example server:

python example/run_server.py

That starts a FastAPI app on http://127.0.0.1:8088 with the MCP endpoint mounted at http://127.0.0.1:8088/mcp.

Stdio Transport

from pymcp import create_app, run_stdio_server


app = create_app()
run_stdio_server(app)

Middleware

Middleware stays separate from capability registration. Use MiddlewareConfig to control CORS, compression, logging, auth hooks, and custom ASGI middleware, then pass it into create_app(). See the hosted Middleware guide for examples.

Scope

• Prompts and resources are advertised only when registered by default
• Registries are copied into an app-scoped manager when create_app() runs
• Streamable HTTP and stdio are the only built-in transports
• Extra transports such as SSE and HTTP NDJSON are intentionally not shipped in pymcp-kit