Kurd

A high-performance Model Context Protocol (MCP) gateway for Python, powered by Rust.

Kurd combines a Python-first developer API with a Rust data plane for MCP routing, upstream aggregation, concurrency control, security, caching, and observability.

Status

Kurd is in beta and is being hardened for production use.

Current release line: 0.3.x

The gateway targets the MCP 2026-07-28 protocol revision while preserving compatibility paths used by existing Kurd applications.

Highlights

• Python-first Router API

• Rust core using Tokio, Axum, Serde, and Reqwest

• MCP server/discover, tools/list, and tools/call

• Local Python tools and mounted upstream MCP servers

• Sync and async Python callbacks

• Concurrent upstream discovery

• Shared HTTP connection pool

• Retry with exponential backoff and jitter

• Circuit breaker

• Tool-list caching with TTL and cache scope

• Graceful HTTP lifecycle: start, stop, status, restart

• Optional bearer authentication

• Request-size and content-type validation

• Upstream URL validation and private-network policy

• Configurable upstream timeout

• Global, per-upstream, and Python callback backpressure

• Request IDs and structured request logging

• Runtime, cache, and upstream metrics

• Cross-platform CI and automated PyPI release workflow

Installation

pip install kurd

Python 3.10 or newer is required.

Quick Start

from kurd import Router

router = Router()

@router.tool()
async def add(a: int, b: int) -> int:
    return a + b

Start the HTTP gateway:

from kurd._kurd import start_http_gateway

start_http_gateway("127.0.0.1:9200")

The MCP endpoint is:

http://127.0.0.1:9200/mcp

Health and operational status are exposed at:

GET /health
GET /status

Mount an Upstream MCP Server

from kurd import Router

router = Router()
router.mount("github", "http://127.0.0.1:9300")

An upstream tool named create_issue is exposed through Kurd as:

github.create_issue

Unmount or refresh the aggregated tool cache:

router.unmount("github")
router.refresh_tools()

Runtime Hardening

Kurd provides explicit concurrency controls:

router.configure_runtime(
    global_concurrency=512,
    upstream_concurrency=64,
    python_concurrency=64,
    request_logging=False,
)

Inspect runtime state:

print(router.runtime_status())

The HTTP /status endpoint also reports runtime, cache, security, upstream latency, retry, and circuit-breaker metrics.

Security

Kurd currently provides a production security baseline:

• maximum MCP request body size

• JSON content-type validation

• optional bearer-token authentication

• upstream URL validation

• configurable private/loopback upstream policy

• configurable upstream request timeout

• sanitized upstream transport errors

• overload rejection through explicit backpressure

For deployments exposed beyond localhost, use TLS at the reverse proxy or ingress layer and apply your normal network-level authentication and authorization controls.

MCP 2026-07-28

Kurd implements the stateless 2026 MCP model used for routable gateway traffic:

• per-request protocol metadata

• MCP-Protocol-Version

• Mcp-Method

• Mcp-Name for tool calls

• server/discover

• deterministic tools/list

• resultType

• ttlMs

• cacheScope

• server identity metadata

Kurd rejects mismatched modern MCP headers and unsupported protocol versions.

Performance

The repository includes end-to-end HTTP load tests in tests/test_load.py.

Example measurements from a Windows development machine:

These are local measurements, not universal performance guarantees. Hardware, operating system, Python version, payload shape, upstream implementation, and network conditions affect results.

Run the benchmark suite with:

python -m pytest tests/test_load.py -q -s

Development

Create and activate a virtual environment, then install the development tools:

python -m pip install --upgrade pip
python -m pip install maturin pytest

Build the native extension:

maturin develop --release

Run the full test suite:

python -m pytest -q

Build release artifacts:

maturin build --release

Architecture

Python application
       |
       v
   Kurd Router
       |
       v
   PyO3 boundary
       |
       v
 Rust MCP gateway
   |          |
   |          +--> Local Python tools
   |
   +-------------> Upstream MCP servers

Rust owns the HTTP server, MCP validation, routing, caching, retries, circuit breaking, backpressure, and operational metrics. Python provides the developer-facing registration and configuration API.

Testing

The current suite covers:

• JSON-RPC parsing and dispatch

• local sync and async tools

• upstream discovery and calls

• concurrent upstream discovery

• cache behavior and invalidation

• mount and unmount

• MCP 2026 request headers and protocol-version checks

• HTTP lifecycle and graceful shutdown

• request-size and content-type security

• bearer authentication

• upstream URL policy

• timeout configuration

• error sanitization

• global and Python callback backpressure

• request ID propagation

• runtime observability

• load and burst behavior

Compatibility

CI targets Windows, Linux, and macOS. Release wheels are built through Maturin.

The project is primarily developed with Python 3.12 and stable Rust; package metadata supports Python 3.10+.

Release Policy

Kurd uses semantic versioning while the public API stabilizes.

• patch releases: bug fixes and packaging corrections

• minor releases: new gateway or MCP capabilities

• 1.0.0: stable public API commitment

Project Structure

kurd/
├── kurd/
│   ├── __init__.py
│   └── router.py
├── src/
│   └── lib.rs
├── tests/
│   ├── test_upstream.py
│   ├── test_load.py
│   └── upstream_server.py
├── Cargo.toml
├── pyproject.toml
├── README.md
└── LICENSE

Contributing

Issues and technical discussions are welcome through the GitHub issue tracker.

Before submitting a change:

cargo check
maturin develop --release
python -m pytest -q

License

MIT.

Name

The name Kurd honors Kurdish identity and heritage.

Bezhi Kurd u Kurdistan.