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:

frompymcpimport (
CapabilitySettings,
ServerSettings,
create_app,
prompt_registry,
resource_registry,
tool_registry,
)
@tool_registry.registerdefadd(a: float, b: float) ->str:
returnstr(a+b)
@prompt_registry.register(description="Create a release summary prompt.")defsummarize_release(topic: str) ->str:
returnf"Summarize the release impact for {topic}."@resource_registry.register(uri="memo://release-plan",name="release_plan",description="Latest release checklist",mime_type="text/markdown",)defrelease_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.",)deftopic_note(topic: str) ->str:
returnf"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 onlyapp=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:

frompymcpimportCapabilitySettings, ServerSettings, create_appapp=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

frompymcpimportcreate_app, run_stdio_serverapp=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 page 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