Skip to main content

​
What is the Surfa MCP Server?

The Surfa MCP Server lets you query your analytics data using natural language through Claude Desktop or any MCP-compatible client. Instead of dashboards, just ask:
  • “What’s my success rate this week?”
  • “Find all errors from yesterday”
  • “Which tools are slowest?”
Get instant answers powered by your real-time analytics data.

​
How It Works

1

Install

Clone and install the Surfa MCP Server
2

Configure

Add your API key to Claude Desktop config
3

Query

Ask questions in natural language
4

Analyze

Get AI-powered insights and recommendations

​
Features

Natural Language Queries

Ask questions in plain English. No SQL, no dashboards.

8 Analytics Tools

Core analytics + V2 cost optimization tools with multi-model estimates.

JSON Responses

Structured data optimized for AI agent consumption.

Multi-Query Workflows

Chain queries together for complex analysis.

​
Remote vs Local MCP

​
Local MCP (STDIO)

  • Runs on your machine
  • Fast, low latency
  • Claude Desktop only
  • No deployment needed

​
Remote MCP (HTTP/SSE)

  • Deployed to cloud (Fly.io, Railway, etc.)
  • Accessible from anywhere
  • Web applications supported
  • Requires deployment

Remote MCP Deployment Guide

Learn how to deploy your MCP to production with HTTP/SSE transport

​
Available Tools

​
Core Analytics (4 tools)

​
1. get_analytics

Get high-level metrics about your MCP server. Example queries:
  • “Show me my analytics overview”
  • “What’s my success rate?”
  • “How many sessions do I have?”
Returns: 
{
  "ok": true,
  "data": {
    "totalSessions": 150,
    "successRate": 85,
    "avgExecutionTime": 245,
    "activeSessions": 12
  }
}

​
2. query_events

Filter and search through your events. Example queries:
  • “Show me all errors from the last 24 hours”
  • “Find tool calls with latency over 1000ms”
  • “Get all session events from yesterday”
Parameters:
  • tool_name - Filter by tool name
  • min_latency / max_latency - Latency range in ms
  • start_date / end_date - ISO 8601 timestamps
  • kind - Event kind (tool, session, runtime)
  • status - Event status (success, error)
  • limit - Max results (default: 100)

​
3. find_highest_latency

Find your slowest queries. Example queries:
  • “What were the slowest queries this week?”
  • “Show me the top 5 slowest tool calls today”
Parameters:
  • time_range - hour, day, week, or month
  • tool_name - Optional: filter by specific tool
  • limit - Number of results (default: 10)

​
4. get_session

Deep-dive into a specific session. Example queries:
  • “Show me details for session abc123”
  • “What happened in session xyz789?”
Parameters:
  • session_id - The session ID to retrieve
Returns: 
{
  "ok": true,
  "data": {
    "session_id": "abc123",
    "status": "completed",
    "started_at": "2026-03-04T12:00:00Z",
    "completed_at": "2026-03-04T12:05:00Z",
    "runtime": {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet",
      "mode": "stdio"
    },
    "events": [...],
    "event_count": 15
  }
}

​
V2 Analytics - Cost Optimization (4 tools)

​
5. find_redundant_executions

Find executions with redundant tool calls that waste tokens and costs. Example queries:
  • “Which sessions have redundant tool calls?”
  • “Show me executions wasting the most money on duplicate calls”
  • “Find redundancy from the last month”
Parameters:
  • time_range - hour, day, week, or month (default: week)
  • min_redundancy - Minimum redundancy score 0.0-1.0 (default: 0.3)
  • limit - Max results (default: 20)
Returns: 
{
  "ok": true,
  "data": {
    "total_found": 20,
    "total_potential_savings": {
      "calls_saved": 327,
      "tokens_estimated": 49050,
      "cost_usd": {
        "gpt_4_turbo": 0.00049,
        "claude_sonnet": 0.00015
      }
    },
    "executions": [...]
  }
}

​
6. find_batch_opportunities

Find tools called multiple times per session that could benefit from batch endpoints. Example queries:
  • “Which tools should I add batch endpoints for?”
  • “What’s my biggest batching opportunity?”
  • “Show me tools that could be batched”
Parameters:
  • time_range - hour, day, week, or month (default: week)
  • min_call_count - Minimum calls per execution (default: 3)
  • limit - Max results (default: 20)
Returns: 
{
  "ok": true,
  "data": {
    "total_opportunities": 5,
    "opportunities": [
      {
        "tool_name": "get_user",
        "execution_count": 15,
        "total_calls": 78,
        "potential_savings": {
          "calls_saved": 63,
          "tokens_estimated": 9450,
          "cost_usd": {...}
        },
        "recommendation": "Add batch_get_user endpoint"
      }
    ]
  }
}

​
7. get_tool_insights

Get comprehensive performance insights for a specific tool. Example queries:
  • “How is get_user performing?”
  • “Analyze the search_database tool”
  • “Show me insights for my slowest tool”
Parameters:
  • tool_name - Name of the tool to analyze (required)
  • time_range - hour, day, week, or month (default: week)
Returns: 
{
  "ok": true,
  "data": {
    "tool_name": "get_user",
    "usage": {
      "execution_count": 45,
      "total_calls": 120,
      "avg_calls_per_execution": 2.7
    },
    "redundancy": {
      "avg_redundancy_rate": 0.25,
      "potential_savings": {...}
    },
    "latency": {
      "mean_ms": 245,
      "p95_ms": 890,
      "max_ms": 1200
    },
    "batch_potential": {...},
    "recommendations": [
      "Consider caching: 25% of calls are redundant",
      "Batch potential: 15 executions make multiple calls"
    ]
  }
}

​
8. get_execution_metrics

Get detailed V2 metrics for a specific execution (enhanced version of get_session). Example queries:
  • “Show me everything about execution abc123”
  • “Debug execution xyz789 with full metrics”
  • “Get V2 metrics for the worst redundancy offender”
Parameters:
  • execution_id - The execution ID to retrieve (required)
Returns: 
{
  "ok": true,
  "data": {
    "execution_id": "abc123",
    "session_outcome": "complete",
    "metrics_v2": {
      "redundancy": {
        "score": 0.45,
        "redundant_calls": 12,
        "potential_savings": {...}
      },
      "batch_opportunities": [...],
      "latency": {
        "mean_ms": 340,
        "slowest_tool": "search_database"
      }
    },
    "total_optimization_potential": {
      "calls_saved": 15,
      "tokens_estimated": 2250,
      "cost_usd": {...}
    }
  }
}

​
Multi-Query Workflows

The real power comes from chaining queries together. Claude can:
  1. Get analytics → sees low success rate
  2. Query events → finds error patterns
  3. Analyze → provides recommendations
Example: 
You: "Analyze my product health"

Claude:
1. Calls get_analytics() → sees 54% success rate
2. Calls query_events(status="error") → finds "Database unavailable"
3. Analyzes patterns → identifies Feb 21-22 outage
4. Provides recommendations:
   - Add database health checks
   - Implement circuit breakers
   - Separate metrics by time window
All in seconds. No dashboards. No SQL.

​
Use Cases

Track product metrics without SQL:
  • “What’s my weekly active users trend?”
  • “Which features are most used?”
  • “What’s causing the drop in success rate?”
Get insights in natural language, share with team instantly.
Debug faster:
  • “Show me all errors in the last hour”
  • “Which tool is failing most often?”
  • “What happened in session abc123?”
Skip log diving, get straight to the issue.
Monitor performance:
  • “What were the slowest queries today?”
  • “Show me latency trends this week”
  • “Are there any performance regressions?”
Proactive monitoring through conversation.
Autonomous analytics: Build PM agents that automatically:
  • Monitor metrics
  • Detect anomalies
  • Investigate issues
  • Generate reports
JSON responses make it easy for agents to consume.

​
Why Use the MCP Server?

No Context Switching

Query analytics without leaving Claude. No switching to dashboards.

Natural Language

Ask questions like you would a teammate. No learning query languages.

AI-Powered Insights

Claude analyzes the data and provides recommendations automatically.

Agent-Ready

JSON responses perfect for building autonomous PM agents.

​
Getting Started

Set Up Claude Desktop

Follow our step-by-step guide to install and configure the Surfa MCP Server.

​
Example Queries

"Show me my analytics overview"
"What's my success rate this week?"
"How many active sessions do I have?"

​
Architecture

You (Natural Language)
    ↓
Claude Desktop
    ↓
Surfa MCP Server (Python)
    ↓
Surfa API (HTTP + Bearer Auth)
    ↓
Your Analytics Data
Security:
  • API key stored locally in Claude Desktop config
  • Never exposed to Claude
  • Workspace-scoped (you only see your data)

​
Next Steps

Claude Desktop Setup

Install and configure the MCP server

API Reference

Complete API documentation with examples

Quickstart Guide

Start tracking events in 5 minutes

GitHub Repository

View source code and contribute