# Python FastMCP

> Add Voxmith analytics to your FastMCP server

## Install

<CodeGroup>
  ```bash pip theme={null}
  pip install voxmith-mcp
  ```

  ```bash uv theme={null}
  uv add voxmith-mcp
  ```
</CodeGroup>

## Integrate

Call `track` after defining your server and tools, before running:

```python theme={null}
from mcp.server.fastmcp import FastMCP
from voxmith_mcp import track, config

server = FastMCP("Your Server Name")

# ... your tools ...

track(server, "your-org-id", config(
    endpoint="https://api.voxmith.com",
    disable_input=False,
    disable_output=False,
))

if __name__ == "__main__":
    server.run()
```

Get your org ID from [app.voxmith.com](https://app.voxmith.com).

## Identify users

Pass an `identify` function to resolve a user from the incoming request context. It receives the raw request object and the process environment, and should return a dict with at least a `userId` key:

```python theme={null}
from voxmith_mcp import track, config

track(server, "your-org-id", config(
    identify=lambda req, env: {
        "userId": req.get("headers", {}).get("x-user-id") or env.get("USER_ID", "anonymous"),
        "email":  req.get("headers", {}).get("x-user-email") or env.get("USER_EMAIL"),
        "role":   req.get("headers", {}).get("x-user-role")  or env.get("USER_ROLE", "user"),
    }
))
```

The function can also be `async`. Return `None` to skip user attribution for a request.

## Options

| Field | Type | Default | Description |
| - | - | - | - |
| `endpoint` | `str` | `https://api.voxmith.com` | API endpoint |
| `disable_input` | `bool` | `False` | Skip capturing tool input arguments |
| `disable_output` | `bool` | `False` | Skip capturing tool output / result |
| `log_level` | `str` | `"INFO"` | Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
| `identify` | `Callable` | `None` | Function `(request, env) → UserIdentity` to resolve user identity per request |

`UserIdentity` is a `Dict[str, Any]` that **must contain a `userId` key**. Other fields (e.g. `email`, `role`) are optional and forwarded as user traits. The identify callable can be sync or async, and may return `None` to skip attribution for a request.

## What appears in Voxmith

* **Tool calls** for FastMCP tool invocations.
* **Events** for every tracked call.
* Failed tool calls remain visible in **Events** with their error details.

## Verify

Call one FastMCP tool from your MCP client, then open [app.voxmith.com](https://app.voxmith.com). Check **Events** first, then **Tool calls**.

## Troubleshooting

* Call `track(...)` after defining tools and before `server.run()`.
* Confirm the org ID is correct.

## Next steps

* [Tool calls](/using-tool-calls): analyze calls from your FastMCP server.
* [Events](/using-events): verify call fields and execution details.
* [Alerts](/using-alerts): monitor important MCP tool conditions.