PyMCP Kit
README.md
# PyMCP Kit
[](https://github.com/Agent-Hellboy/py-mcp/actions/workflows/python-ci.yml)
[](https://codecov.io/gh/Agent-Hellboy/py-mcp)
[](https://modelcontextprotocol.io/specification/2025-11-25)
[](https://agent-hellboy.github.io/py-mcp/runtime-surface/#supported-protocol-versions)
[](https://pypi.org/project/pymcp-kit/)
[](https://pepy.tech/projects/pymcp-kit)
[](https://agent-hellboy.github.io/py-mcp/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[Documentation](https://agent-hellboy.github.io/py-mcp/) | [Quick Start](https://agent-hellboy.github.io/py-mcp/getting-started/) | [Tasks](https://agent-hellboy.github.io/py-mcp/tasks/) | [Security](https://agent-hellboy.github.io/py-mcp/security/) | [Middleware](https://agent-hellboy.github.io/py-mcp/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:
```bash
pip install pymcp-kit
```
For local development from this repo:
```bash
pip install -e .
```
Register tools, prompts, and resources, then build an app:
```python
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:
```python
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:
```python
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](https://agent-hellboy.github.io/py-mcp/runtime-surface/) for protocol versions, HTTP endpoints, and capability settings.
## Example Server
Run the bundled example server:
```bash
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
```python
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 page](https://agent-hellboy.github.io/py-mcp/middleware/) 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`
This server cannot be deployed
Maintenance
ActivityStale
ResponsivenessWithin a week