Surfa Ingest SDK

Analytics for MCP Servers and AI Agents - Track usage, performance, and task completion whether your server runs locally or remotely.

Why Surfa Ingest?

For MCP Server Builders

Get visibility into how your MCP server is being used - whether it's installed locally on users' machines or hosted remotely:

📊 Gain Visibility You Wouldn't Have Otherwise

• Local MCP servers: Track usage even when installed on users' machines (Claude Desktop, Cursor, etc.)
• Remote MCP servers: Get structured analytics beyond basic server logs

🎯 Understand Your Users

• Which tools are most popular
• Which AI clients are using your server (Claude, ChatGPT, Cursor)
• Real-time usage patterns and trends
• Geographic distribution and platform breakdown

🚀 Optimize Based on Real Data

• Performance metrics (latency, error rates)
• Task completion tracking (did the user actually accomplish their goal?)
• Identify bottlenecks and failure points
• A/B test improvements

💰 Enable Usage-Based Pricing

• Track API calls and tool usage
• Monitor quota consumption
• Build monetization models

🔍 Debug Issues Faster

• See exactly what's failing and where
• Trace user sessions end-to-end
• Identify retry patterns and error sequences

Privacy-First Design

• ✅ No PII collected by default
• ✅ Users can opt-out via environment variable
• ✅ You control what data is sent
• ✅ GDPR and privacy-compliant

Quick Start: one line

pip install surfa-ingest

from fastmcp import FastMCP
from surfa_ingest import with_surfa

mcp = with_surfa(FastMCP("my-server"))

Set SURFA_API_KEY (create one at app.surfa.dev → Settings → API Keys) and every tool call shows up in your dashboard: tool name, arguments (secrets masked), latency, errors, and which client called it. No per-tool decorators; tools added later are captured too.

Works with:

It never hurts your server: events are queued in memory (bounded) and uploaded on a background thread; if Surfa is slow, down or rejects the key, tool calls behave exactly as before. Messages go to stderr only, never stdout (the stdio channel).

Serverless or short-lived processes: call flush_surfa() before returning. A server with its own SIGTERM handler should call shutdown_surfa() in it.

Full guide: docs.surfa.dev/python-setup. Example: examples/fastmcp_server.py.

Manual events (advanced)

SurfaClient sends events you build yourself, for code that isn't an MCP server:

import os

from surfa_ingest import SurfaClient

with SurfaClient(ingest_key=os.environ["SURFA_API_KEY"]) as client:
    client.tool_started("search", args={"query": "mcp"})
    client.tool_completed("search", latency_ms=120)

For MCP servers prefer with_surfa(): it records the fields Surfa's metrics read (input, correlation_id, sessions per client connection), which manual events often miss.

What You Get

Real-Time Dashboards

• 📈 Tool usage trends
• ⚡ Performance metrics (P50, P95, P99 latency)
• ✅ Task completion rates
• 🔴 Error rates and types
• 👥 Active users and sessions

Deterministic Agent Metrics

• Task Completion: Did the user actually accomplish their goal?
• Tool Calls: How many tools were invoked?
• Retries: Repeated calls with same parameters
• Recovery: Did the agent recover from errors?
• Latency: P95 and total latency tracking

Client Intelligence

• Which AI clients are using your MCP (Claude, ChatGPT, Cursor)
• Platform distribution (macOS, Linux, Windows)
• Client versions and configurations

Key Features

• 🚀 Event Buffering - Automatic batching with configurable buffer size
• 🔄 Auto-Retry - Built-in retry logic with exponential backoff
• 📦 Context Manager - Automatic session lifecycle management
• 🏷️ Runtime Metadata - Track AI provider, model, and configuration
• ✨ MCP Context Auto-Detection (v0.2.0+) - Automatically extract client_id, session_id from MCP context
• 📊 Deterministic Agent Metrics - Track task completion, retries, recovery, and performance metrics that traditional analytics platforms don't provide
• ✅ Event Validation - Client-side validation before sending
• 🔍 Correlation IDs - Link related events together
• 🛡️ Type Safety - Full type hints and IDE autocomplete
• 🔒 Privacy-First - No PII by default, user opt-out support

What makes Surfa different: We calculate deterministic metrics like task completion, retry detection, and recovery rates automatically from your event stream - metrics that generic analytics platforms can't provide because they don't understand AI agent behavior.

Learn More

📚 Documentation

• Full API Reference - Complete method documentation
• Deterministic Metrics - How we calculate task completion, retries, and recovery
• Advanced Usage - Context managers, error handling, logging
• Examples - More code examples for different use cases

🔗 Links

• 📦 PyPI: https://pypi.org/project/surfa-ingest/
• 📝 Changelog: CHANGELOG.md
• 🐛 Issues: https://github.com/gamladz/surfa/issues
• 💬 Discussions: https://github.com/gamladz/surfa/discussions

Quick Reference

Deterministic Metrics (Auto-Calculated)

When you send events using this SDK, the Surfa platform automatically calculates these metrics for each execution:

Automatically Calculated Metrics

See full metrics documentation →

Development Status

Current Version: 0.2.0 (Alpha)

This SDK is in active development. The API may change in future versions.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Made with ❤️ for MCP builders