Skip to main content
This guide shows how to integrate Agnost analytics with your FastMCP server.

​
Step 1: Install Agnost

pip install agnost

​
Step 2: Import and Initialize

from mcp.server.fastmcp import FastMCP
from agnost import track, config

# Create your FastMCP server
server = FastMCP("Your Server Name")

​
Step 3: Define Your Tools

Add your tools as normal: 
@server.tool()
async def query_data(query: str, conversation_id: str) -> str:
    """Query data with context"""
    context = server.get_context()
    session_id = hex(id(context.session))
    return f"Session: {session_id} - Query: {query} - Conversation: {conversation_id}"

@server.tool()
async def add_numbers(number1: int, number2: int) -> str:
    """Add two numbers together"""
    req_context = server._mcp_server.request_context.session._client_params
    print(f"Client: {req_context.clientInfo.name}")
    return f"Result: {number1 + number2}"

​
Step 4: Add Analytics

Create the mandatory configuration object and add analytics: 
# Add analytics with your org_id from https://app.agnost.ai
track(server, "your-org-id-here", config(
    endpoint="https://api.agnost.ai",
    disable_input=False,
    disable_output=False
))

​
Step 5: Run Your Server

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

​
Complete Example

Here’s a complete working example: 
from mcp.server.fastmcp import FastMCP
from agnost import track, config

# Create server
example_mcp = FastMCP("My Example MCP")

# Define tools
@example_mcp.tool()
async def query_session(query: str, conversationId: str) -> str:
    """Query Session ID
    Args:
    - query (str): query from client
    - conversationID (str): unique conversation ID from client
    """
    context = example_mcp.get_context()
    sessionID = hex(id(context.session))
    return f"sessionID: {sessionID}_{query}_{conversationId}"

@example_mcp.tool()
async def add_numbers(number1: int, number2: int) -> str:
    """Adds 2 numbers. Args: number 1 and number 2"""
    req_context = example_mcp._mcp_server.request_context.session._client_params
    print(f"client: {req_context.clientInfo.name}")
    return f"Addition: {number1 + number2}"

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

# Run server
if __name__ == "__main__":
    example_mcp.run()

​
Configuration Options

The config object is mandatory and must include all 3 fields:
FieldTypeDescription
endpointstrAPI endpoint URL
disable_inputboolWhether to disable input tracking
disable_outputboolWhether to disable output tracking

​
Troubleshooting

Server not starting?
  • Check that FastMCP is properly installed: pip install fastmcp
  • Verify your tool definitions are correct
  • Ensure no port conflicts
No analytics data?
  • Verify your organization ID is correct
  • Check that the Agnost backend is running on the configured endpoint
  • Look for any error messages in your server logs
Import errors?
  • Update Agnost: pip install --upgrade agnost
  • Ensure you’re using the correct FastMCP import path
⌘I