Kurd MCP

pip install kurd

from kurd import Router
from kurd._kurd import start_http_gateway

router = Router()

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

# Blocks until stop_http_gateway() is called or the process exits.
start_http_gateway("0.0.0.0:9200")

curl -s http://localhost:9200/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add","arguments":{"a":3,"b":4}}}'

{"jsonrpc":"2.0","id":1,"result":{"resultType":"complete","content":[{"type":"text","text":"7"}],"isError":false}}

Usage: kurd <COMMAND>

Commands:
  serve   Start the HTTP MCP gateway

Options:
  -h, --help  Show this message and exit

kurd serve [--host HOST] [--port PORT] [--token TOKEN]

# Start on port 8000 with no authentication
kurd serve

# Start on a specific address with a bearer token
kurd serve --host 127.0.0.1 --port 9200 --token my-secret

# Use an environment variable for the token
KURD_AUTH_TOKEN=my-secret kurd serve --port 9200

from kurd import Router

router = Router()

@router.tool()
async def search(query: str, limit: int = 10) -> list[str]:
    """Search the knowledge base."""
    return [f"result {i}" for i in range(limit)]

router.reload_tool("search", new_search_function)

router.unregister_tool("search")

router.list_tools()      # -> ["add", "search", ...]
router.list_upstreams()  # -> [("github", "http://..."), ...]

router.mount("github", "http://github-mcp.internal:9300")
router.mount("jira",   "http://jira-mcp.internal:9300")

github.create_issue
jira.create_ticket

router.unmount("github")   # stop routing to this upstream
router.refresh_tools()     # expire the tool list cache immediately

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/list",
  "params": { "filter": { "namespace": "github" } }
}

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/list",
  "params": { "filter": { "search": "file" } }
}

{
  "result": {
    "tools": [...],
    "_kurd": { "available": 12, "returned": 3 }
  }
}

router.set_admin_token("admin-secret")
# router.clear_admin_token()  # fall back to MCP bearer token / open

from kurd import set_admin_token, clear_admin_token
set_admin_token("admin-secret")

# List
curl http://localhost:9200/admin/servers

# Add / replace
curl -X POST http://localhost:9200/admin/servers \
  -H 'Content-Type: application/json' \
  -d '{"name": "github", "url": "http://github-mcp.internal:9300/mcp"}'

# Remove
curl -X DELETE http://localhost:9200/admin/servers/github

# All tools with source label
curl http://localhost:9200/admin/tools

# Reload (expire cache)
curl -X POST http://localhost:9200/admin/tools/reload

# List upstream namespaces
curl http://localhost:9200/admin/tools/namespaces

from kurd import Router, RuntimeConfig

router = Router()
router.configure_runtime(RuntimeConfig(
    # Concurrency
    global_concurrency   = 512,   # max simultaneous in-flight requests
    upstream_concurrency = 64,    # max simultaneous upstream calls
    python_concurrency   = 64,    # max simultaneous Python tool calls
    upstream_timeout_ms  = 30_000,

    # Logging
    request_logging      = False, # structured per-request log lines

    # Rate limiting
    rate_limiting_enabled   = True,
    rate_limit_per_ip_rps   = 1_000,
    rate_limit_global_rps   = 10_000,

    # IP allowlist (None = allow all)
    ip_allowlist         = ["192.168.1.0/24", "10.0.0.1"],

    # Tool cache
    tools_cache_ttl_ms   = 30_000,

    # Enterprise (all off by default)
    enable_dlq                  = False,
    enable_idempotency          = False,
    secrets_backend             = "env",
    enable_webhooks             = False,
    enable_distributed_state    = False,
    distributed_state_backend   = "memory",
    redis_url                   = "redis://localhost:6379/0",
    enable_distributed_tracing  = False,
))

router.configure_runtime(request_logging=True, rate_limiting_enabled=True)

status = router.runtime_status()
# {
#   "global_active": 3,
#   "global_limit": 512,
#   "python_active": 1,
#   "upstream_metrics": {...},
#   "cache": {"hits": 142, "misses": 3},
#   ...
# }

from kurd._kurd import set_http_bearer_token, clear_http_bearer_token

set_http_bearer_token("my-production-token")
# clear_http_bearer_token()  # disable authentication

KURD_AUTH_TOKEN=my-production-token kurd serve

from kurd import set_ip_allowlist, clear_ip_allowlist

set_ip_allowlist(["10.0.0.1", "10.0.0.2"])
clear_ip_allowlist()  # allow all IPs again

router.configure_runtime(
    rate_limiting_enabled=True,
    rate_limit_per_ip_rps=1_000,
    rate_limit_global_rps=10_000,
)

from kurd import Router, TenantManager

manager = TenantManager()

# Add tenants with explicit tool allowlists
manager.add_tenant("acme",   name="Acme Corp",  allowed_tools=["add", "search"], api_key="sk-acme")
manager.add_tenant("devops", name="DevOps Team", allowed_tools=["*"],            api_key="sk-ops")

router = Router()
router.set_policy_engine(manager)
# router.clear_policy_engine()  # disable, all requests allowed again

curl http://localhost:9200/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-acme' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# → returns only ["add", "search"]

kurd_policy_denied_total   # counter — requests blocked by the policy engine

router.configure_runtime(request_logging=True)

KURD_LOG=kurd=debug kurd serve   # debug, info, warn, error
RUST_LOG=info kurd serve         # fallback if KURD_LOG is unset

curl http://localhost:9200/metrics

# prometheus.yml
scrape_configs:
  - job_name: kurd
    static_configs:
      - targets: ["localhost:9200"]
    metrics_path: /metrics
    scrape_interval: 15s

# datadog.yaml
instances:
  - openmetrics_endpoint: http://localhost:9200/metrics
    namespace: kurd
    metrics: ["kurd_.*"]

from kurd import Router
from kurd.telemetry import setup_otel

router = Router()

# Activates Rust-side OTLP export. setup_otel returns an OTELTracer for
# any additional Python-side instrumentation you want.
setup_otel(
    service_name = "my-gateway",
    endpoint     = "http://otel-collector:4318",  # OTLP HTTP receiver
)

router.configure_otel("http://otel-collector:4318", service_name="my-gateway")
# router.clear_otel()  # disable export

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

from kurd.health_checks import HealthCheckManager

hc = HealthCheckManager()

# Register a custom check
async def check_db():
    ...

hc.register_check("database", check_db, critical=True)

# Kubernetes probes
readiness = await hc.check_readiness()  # all critical checks pass
liveness  = await hc.check_liveness()   # process is running and active

from kurd import TenantManager

manager = TenantManager()
manager.add_tenant(
    tenant_id="acme",
    name="Acme Corp",
    quota_rps=100,
    allowed_tools=["add", "search"],
    api_key="sk-acme",
)

from kurd.billing import BillingManager

billing = BillingManager()
billing.set_pricing({"add": {"per_call": 0.001, "per_latency_ms": 0.0001}})
billing.track_call(tenant_id="acme", tool_name="add", latency_ms=12.5, success=True)

report = billing.get_usage_report("acme", period="2026-08")

router.configure_runtime(enable_idempotency=True)
mgr = router.get_idempotency()

is_dup, cached = mgr.check_idempotent_key("req-abc-123", tenant_id="acme")
if is_dup:
    return cached

result = run_tool()
mgr.store_result("req-abc-123", "acme", result)

router.configure_runtime(enable_dlq=True, dlq_storage_path="/data/kurd/dlq")
dlq = router.get_dlq()

dlq.add_message(request_id="req-123", tenant_id="acme",
                tool_name="add", arguments={"a":1,"b":2}, error="timeout")

dlq.register_replay_handler("add", handler)
success, error = dlq.replay_message("dlq_abc123")

stats = dlq.get_statistics(tenant_id="acme")
dlq.cleanup_archived(days=30)

from kurd.secrets_management import SecretsManager

# Kubernetes in-cluster | HashiCorp Vault | AWS Secrets Manager | env (default)
manager = SecretsManager(backend="vault",
                          vault_addr="https://vault.example.com",
                          vault_token="s.xxxxx")

secret = manager.get_secret("db_password")

router.configure_runtime(enable_webhooks=True)
hooks = router.get_webhooks()

hooks.register_webhook(
    url="https://example.com/hooks",
    events=["error", "rate_limit_exceeded"],
    tenant_id="acme",
)

router.configure_runtime(
    enable_distributed_state=True,
    distributed_state_backend="redis",
    redis_url="redis://localhost:6379/0",
)
state = router.get_distributed_state()
state.set("gateway:version", 42)
state.increment("counters:acme:calls")

from kurd.distributed_tracing import extract_context

trace = extract_context(incoming_headers)
span  = trace.create_span("tool_execution", {"tool": "add"})
span.set_attribute("result", 42)
span.end()

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

Python application
       │
       ▼
  kurd.Router                      ← Python API layer
       │
       ├── Policy engine (set_policy_engine)
       │   TenantManager callbacks wired into Rust hot path
       │
       ├── Enterprise modules (optional, lazy)
       │   multitenancy · billing · idempotency · DLQ
       │   secrets · webhooks · distributed state
       │
       ▼
   PyO3 boundary
       │
       ▼
  Rust MCP gateway (Axum + Tokio)
       │
       ├── HTTP handler  ─────────────────────────────────┐
       │   content-type · auth · IP allowlist              │
       │   rate limiting · concurrency backpressure        │
       │   CORS · request ID · W3C traceparent             │
       │   OTLP span export (fire-and-forget)              │
       │                                                   │
       ├── Admin API (/admin/*)                            │
       │   server CRUD · tool listing · cache reload       │
       │                                                   │
       ├── MCP dispatcher                                  │
       │   initialize · ping · server/discover             │
       │   tools/list (paginated, filtered, _kurd meta)    │
       │   tools/call (policy gate) · resources · prompts  │
       │   completion · logging · notifications (202)      │
       │                                                   │
       ├── Local Python tools ◄── PyO3 callback            │
       │   (Rayon-parallel batch parsing)                  │
       │                                                   │
       └── Upstream MCP servers                           │
           retry · circuit breaker · cache · metrics      ◄┘

pip install maturin pytest

# Development build (fast iteration)
maturin develop

# Optimised build (benchmarks, pre-release testing)
maturin develop --release

# Release wheel
maturin build --release

python -m pytest -q

cargo check
cargo clippy -- -D warnings

kurd-mcp/
├── kurd/
│   ├── __init__.py            # Public API + __version__
│   ├── py.typed               # PEP 561 marker
│   ├── cli.py                 # `kurd serve` entry point
│   ├── router.py              # Router class + RuntimeConfig
│   ├── telemetry.py           # OpenTelemetry integration
│   ├── health_checks.py       # Readiness and liveness probes
│   ├── authorization.py       # RBAC helpers
│   ├── multitenancy.py
│   ├── billing.py
│   ├── idempotency.py
│   ├── dead_letter_queue.py
│   ├── secrets_management.py
│   ├── webhooks.py
│   ├── distributed_state.py
│   ├── distributed_tracing.py
│   └── ...
├── src/
│   └── lib.rs                      # Rust data plane (~3500 lines)
├── tests/
│   ├── test_core.py
│   ├── test_http_gateway.py        # Integration tests (module-scoped gateway)
│   ├── test_admin_api.py           # P1 — Admin HTTP API
│   ├── test_tool_filtering.py      # P2 — Per-tenant tools/list filtering
│   ├── test_tool_discovery.py      # P3 — Client-requested filter + _kurd metadata
│   ├── test_otel.py                # P4 — traceparent / OTLP export
│   ├── test_upstream.py
│   ├── test_load.py
│   ├── test_prometheus_metrics.py
│   └── upstream_server.py          # In-process upstream fixture
├── Cargo.toml
├── pyproject.toml
├── LICENSE
└── README.md

cargo check
cargo clippy -- -D warnings
maturin develop --release
python -m pytest -q