Installation

The Python SDK ships as spanly on PyPI. It is pure ASGI3 middleware: it works with FastAPI, Starlette, or any other ASGI app, including the app mcp's streamable_http_app() returns.

Install

pip install spanly
# or
uv add spanly
# or
poetry add spanly

Supported Python versions

• Python 3.10+
• Pure ASGI3: works under any ASGI server (uvicorn, hypercorn, daphne).

Configure the API key

SpanlyMiddleware reads the API key from the api_key argument, falling back to the SPANLY_API_KEY environment variable. Always source it from the environment, never hard-code it:

import os

from spanly import SpanlyMiddleware

app.add_middleware(SpanlyMiddleware, api_key=os.environ["SPANLY_API_KEY"])

Never hard-code the key. Get one by signing in at spanly.com, opening your project, and going to Settings → API keys. The region (us / eu) is encoded in the key prefix and auto-detected.

When to use the SDK vs the CLI

Mount SpanlyMiddleware in front of your MCP server when it runs over ASGI. It needs no extra process, no sidecar, and no separate binary.

Reach for the Spanly CLI (@spanly/spanly) instead when:

• Your MCP server speaks stdio, not HTTP.
• Your server is not Node or Python (Go, Rust, Java, and so on).
• You are running a Mend shim or canary (Mend rewriting lives in the CLI only, not in this SDK).
• You are on AWS Lambda, where this SDK's delivery guarantees do not hold.

npx -y @spanly/spanly run -- python -m my_mcp