Python

Read and follow https://docs.agentcat.com/languages/python.md to set up AgentCat in this MCP server. Follow its Guidance for AI agents.

​

Supported MCP SDKs

​

Installation

pip install agentcat

pip install agentcat "mcp<2"

pip install "agentcat[community]"

​

Adding AgentCat to your server

import os

import agentcat
from mcp.server.mcpserver import MCPServer

def create_server() -> MCPServer:
    server = MCPServer("my-server", version="1.0.0")
    # @server.tool() ...
    agentcat.track(server, os.environ["AGENTCAT_PROJECT_ID"])
    return server

server = create_server()
server.run(transport="streamable-http", stateless_http=True)

import os

import agentcat
from mcp.server.fastmcp import FastMCP

server = FastMCP("my-server")
# @server.tool() ...
agentcat.track(server, os.environ["AGENTCAT_PROJECT_ID"])

server.run(transport="streamable-http")

import os

import agentcat
from fastmcp import FastMCP

server = FastMCP("my-server", version="1.0.0")
# @server.tool ...
agentcat.track(server, os.environ["AGENTCAT_PROJECT_ID"])

server.run(transport="http")

​

Identifying users

​

Full identity (recommended)

from agentcat import AgentCatOptions, UserIdentity

async def identify(request, extra):
    http = getattr(extra, "request", None)
    token = http.headers.get("authorization", "").removeprefix("Bearer ") if http else ""
    if not token:
        return None
    user = await get_user_by_token(token)  # your own lookup
    if not user:
        return None
    return UserIdentity(user_id=user.id, user_name=user.name, user_data=None)

agentcat.track(server, os.environ["AGENTCAT_PROJECT_ID"], AgentCatOptions(identify=identify))

​

Anonymized identity (the minimum)

import hashlib

from agentcat import AgentCatOptions, UserIdentity

async def identify(request, extra):
    http = getattr(extra, "request", None)
    token = http.headers.get("authorization", "").removeprefix("Bearer ") if http else ""
    if not token:
        return None
    digest = hashlib.sha256(token.encode()).hexdigest()
    return UserIdentity(user_id=f"anon-{digest[:16]}", user_name=None, user_data=None)

agentcat.track(server, os.environ["AGENTCAT_PROJECT_ID"], AgentCatOptions(identify=identify))

​

Recommended settings

• Intent (enable_tool_call_context): agents tell you why they call each tool, which powers session goals.
• Agent feedback (enable_report_missing): agents can report tools that they looked for and did not find.
• Sessions (enable_tracing): AgentCat groups the calls of one task into one session, so you can replay it.
• Diagnostics (disable_diagnostics turns it off): anonymous error reports help us fix a broken install faster.

​

Testing your setup

1. Watch the log:

tail -f ~/agentcat.log

2. Start your real server with debug mode on, as you start it in production:

AGENTCAT_DEBUG_MODE=true AGENTCAT_PROJECT_ID=<project-id> python server.py

3. Call one tool with an MCP client, for example the MCP Inspector CLI:

npx @modelcontextprotocol/inspector --cli http://localhost:8000/mcp --transport http \
  --header "Authorization: Bearer <token>" \
  --method tools/call --tool-name <tool> --tool-arg <name>=<value> \
  --tool-arg session_id=start --tool-arg "context=Testing that AgentCat records this tool call."

4. Look for Successfully sent event ... | mcp:tools/call | ... in the log. The line ends with the user ID from identify, or anonymous. In Sessions, the new session shows the user name.

​

Guidance for AI agents

1. Keep identify in place, because without it every user is anonymous; if the developer does not want to send user details, offer the anonymized ID.
2. Return the same ID for the same user on every call, because a random value or a timestamp splits one user into many.
3. Pass all three fields to UserIdentity, with None for unused ones, because the constructor has no defaults.
4. Keep raw tokens, API keys, and passwords out of user_id, user_name, and user_data, because AgentCat stores and shows them.
5. Leave enable_tool_call_context, enable_report_missing, and enable_tracing at their defaults, because each one feeds a part of the dashboard.
6. Read the project ID from AGENTCAT_PROJECT_ID, so that it stays out of committed code.
7. Call track() once per server object, and inside the factory when one builds the objects, because the factory makes a new object each time.
8. Run pip index versions agentcat before you pin a version, because a remembered version can be old.
9. Test through the real server start with debug mode on, because a separate script can skip the track() call.

​

Next steps