Installation

The Python SDK ships as spanly on PyPI. It works with any MCP server built on mcp (the official @modelcontextprotocol Python SDK) or one that exposes a low-level Server instance.

Install

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

Supported Python versions

• Python 3.10+
• The SDK uses anyio for async transport interception, so it works with both asyncio and trio event loops.

Configure the API key

The client reads SPANLY_API_KEY from the environment by default – no arguments needed:

from spanly import SpanlyClient

client = SpanlyClient()  # reads SPANLY_API_KEY from env

You can also pass it explicitly:

import os
from spanly import SpanlyClient

client = SpanlyClient(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

For most users the CLI is the easier path – it wraps your MCP server with zero code changes and works for any language.

Reach for the Python SDK when you need:

• Per-request hooks (on_collect, on_error) – mutate, filter, or drop packets in Python.
• Per-request multi-tenant tagging that depends on Python-side state (auth scope, async context vars, request bodies).
• In-process embedding – no extra binary or sidecar.

If none of those apply, prefer the CLI.