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.

4 Analytics Tools

Get analytics, query events, find slow queries, inspect sessions.

JSON Responses

Structured data optimized for AI agent consumption.

Multi-Query Workflows

Chain queries together for complex analysis.

​
Available 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
  }
}

​
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