> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agnost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python FastMCP

> Add Agnost AI analytics to your FastMCP server

## Install

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

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

## Integrate

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

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

server = FastMCP("Your Server Name")

# ... your tools ...

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

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

Get your org ID from [app.agnost.ai](https://app.agnost.ai).

## 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 agnost_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.agnost.ai` | 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.