Python

The Python SDK instruments servers built with FastMCP (2.x–4.x) and the official MCP Python SDK — both the 1.27+ FastMCP class and the 2.x MCPServer. Python 3.10+.

Install

pip install "armature-mcp-analytics[fastmcp]"

pip install "armature-mcp-analytics[mcp]"

The base package has no runtime dependencies; the extras pull in the framework you use (fastmcp>=2,<5 or mcp>=1.27,<3).

Set your API key

ANALYTICS_INGEST_API_KEY=<your ingest key>
ANALYTICS_INGEST_URL=<your region's ingest URL>

Copy both values from the dashboard when you mint the key. US workspaces can omit ANALYTICS_INGEST_URL (the SDK defaults to the US endpoint); EU workspaces must set it to https://eu.armature.tech/api/mcp-analytics/ingest. If the key is missing, the SDK quietly no-ops — your server keeps working, and no data is sent.

Instrument your server

Call instrument_fastmcp once, before registering tools:

server.py

from fastmcp import FastMCP
from armature_mcp_analytics import instrument_fastmcp

mcp = FastMCP("Customer MCP")
instrument_fastmcp(mcp)

@mcp.tool
def lookup_customer(customer_id: str) -> dict:
    """Look up a customer by ID."""
    return {"customer_id": customer_id, "status": "active"}

mcp.run()

Works identically with the official SDK’s FastMCP:

from mcp.server.fastmcp import FastMCP
from armature_mcp_analytics import instrument_fastmcp

mcp = FastMCP("Customer MCP")
instrument_fastmcp(mcp)

And with the official SDK 2.x, which renamed the server class:

from mcp.server.mcpserver import MCPServer
from armature_mcp_analytics import instrument_fastmcp

mcp = MCPServer("Customer MCP")
instrument_fastmcp(mcp)

Instrumentation is idempotent — calling instrument_fastmcp twice does not double-count. Sync and async tool handlers are both supported.

Custom dispatcher

If you handle tools/list and tools/call yourself, use the recorder directly:

from armature_mcp_analytics import create_analytics_recorder

analytics = create_analytics_recorder()

async def lookup_customer(args, context):
    return {"customer_id": args["customer_id"], "status": "active"}

analytics.tool(
    {
        "name": "lookup_customer",
        "description": "Look up a customer by ID.",
        "inputSchema": {
            "type": "object",
            "properties": {"customer_id": {"type": "string"}},
            "required": ["customer_id"],
        },
    },
    lookup_customer,
)

tools = analytics.tool_definitions()                       # tools/list
result = await analytics.dispatch(name, args, context)     # tools/call

Using stateless_http=True, or deploying to serverless? Wrap your ASGI app in StatelessHttpSessionMiddleware and set "delivery": "await". Without the middleware, a stateless FastMCP app issues no Mcp-Session-Id at all, so calls arrive with no session identity: Armature falls back to heuristic grouping, separate conversations from the same caller can run together, and Client shows as Unknown. See Stateless & serverless servers.

Configuration

Pass options as a dict under the armature key. Both snake_case and camelCase keys are accepted:

instrument_fastmcp(mcp, {
    "armature": {
        "delivery": "background",
        "timeout_ms": 5000,
        "on_error": lambda err, batch: print("analytics delivery failed", err),
    }
})

Option	Default	Description
`api_key`	`ANALYTICS_INGEST_API_KEY` env var	API key used to authenticate ingestion.
`endpoint_url`	US ingest endpoint	Override with `ANALYTICS_INGEST_URL` or this option; EU workspaces must use the EU endpoint.
`enabled`	`True`	Set `False` to disable capture entirely.
`delivery`	`"background"`	`"background"` posts events off the request path; `"await"` sends before returning (use in serverless).
`timeout_ms`	`5000`	Delivery timeout in milliseconds.
`actor_id`	Derived from request auth	A string or callable (sync or async) used to attribute calls to a user. See Identifying users.
`actor_identifier`	`None`	Attach a caller-provided identifier verbatim. See Identifying users.
`emit`	Network emitter	Replace delivery with your own callable — useful in tests.
`on_error`	`None` (silent)	Called when delivery fails. Failures never reach your tools — set this in production so they’re visible.
`capture_telemetry`	`True`	Set `False` to disable conversation-derived telemetry while keeping call analytics.
`request_capability`	On	Injects the `request_capability` tool (see What the SDK captures); set `False` to disable.

Flush on shutdown

With background delivery, drain pending events before the process exits:

instrumentation = instrument_fastmcp(mcp)
# ... on shutdown:
await instrumentation.recorder.flush()

Verify locally

Capture batches in memory instead of sending them:

batches = []
instrument_fastmcp(mcp, {"armature": {"emit": batches.append, "delivery": "await"}})

# call a tool through the MCP client, then:
event = next(e for b in batches for e in b["events"] if e["kind"] == "tool_call")
assert event["metadata"]["tool_name"] == "lookup_customer"

Troubleshooting

Telemetry fields missing from tool schemas

FastMCP builds the advertised schema from your function’s type hints, so the SDK adds a keyword-only telemetry parameter to instrumented functions. If you post-process signatures or schemas yourself, make sure that parameter survives.

HTTP sessions all look anonymous

The SDK reads the Mcp-Session-Id header, including on FastMCP versions that exclude it from get_http_headers() by default. If you run a custom ASGI stack, make sure the header reaches the app.

No data arrives

Check that ANALYTICS_INGEST_API_KEY is set in the server’s environment (missing keys no-op silently by design), that ANALYTICS_INGEST_URL matches your workspace region — EU keys are rejected by the US endpoint — and pass an on_error hook to surface delivery failures.

Getting started

Analytics

Evaluation

SDKs

Armature MCP

Privacy & security

Install

Set your API key

Instrument your server

Custom dispatcher

Configuration

Flush on shutdown

Verify locally

Troubleshooting

​Install

​Set your API key

​Instrument your server

​Custom dispatcher

​Configuration

​Flush on shutdown

​Verify locally

​Troubleshooting

Install

Set your API key

Instrument your server

Custom dispatcher

Configuration

Flush on shutdown

Verify locally

Troubleshooting