> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Overview

> Query your Surfa analytics with natural language

## 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

<Steps>
  <Step title="Install">
    Clone and install the Surfa MCP Server
  </Step>

  <Step title="Configure">
    Add your API key to Claude Desktop config
  </Step>

  <Step title="Query">
    Ask questions in natural language
  </Step>

  <Step title="Analyze">
    Get AI-powered insights and recommendations
  </Step>
</Steps>

## Features

<CardGroup cols={2}>
  <Card title="Natural Language Queries" icon="message-question">
    Ask questions in plain English. No SQL, no dashboards.
  </Card>

  <Card title="8 Analytics Tools" icon="wrench">
    Core analytics + V2 cost optimization tools with multi-model estimates.
  </Card>

  <Card title="JSON Responses" icon="brackets-curly">
    Structured data optimized for AI agent consumption.
  </Card>

  <Card title="Multi-Query Workflows" icon="diagram-project">
    Chain queries together for complex analysis.
  </Card>
</CardGroup>

## 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

<Card title="Remote MCP Deployment Guide" icon="cloud" href="/remote-mcp-deployment" horizontal>
  Learn how to deploy your MCP to production with HTTP/SSE transport
</Card>

## 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Product Managers" icon="chart-line">
    **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.
  </Accordion>

  <Accordion title="Developers" icon="code">
    **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.
  </Accordion>

  <Accordion title="DevOps Teams" icon="server">
    **Monitor performance:**

    * "What were the slowest queries today?"
    * "Show me latency trends this week"
    * "Are there any performance regressions?"

    Proactive monitoring through conversation.
  </Accordion>

  <Accordion title="AI Agents" icon="robot">
    **Autonomous analytics:**
    Build PM agents that automatically:

    * Monitor metrics
    * Detect anomalies
    * Investigate issues
    * Generate reports

    JSON responses make it easy for agents to consume.
  </Accordion>
</AccordionGroup>

## Why Use the MCP Server?

<CardGroup cols={2}>
  <Card title="No Context Switching" icon="arrows-turn-to-dots">
    Query analytics without leaving Claude. No switching to dashboards.
  </Card>

  <Card title="Natural Language" icon="comment">
    Ask questions like you would a teammate. No learning query languages.
  </Card>

  <Card title="AI-Powered Insights" icon="sparkles">
    Claude analyzes the data and provides recommendations automatically.
  </Card>

  <Card title="Agent-Ready" icon="robot">
    JSON responses perfect for building autonomous PM agents.
  </Card>
</CardGroup>

## Getting Started

<Card title="Set Up Claude Desktop" icon="rocket" href="/claude-desktop-setup" horizontal>
  Follow our step-by-step guide to install and configure the Surfa MCP Server.
</Card>

## Example Queries

<CodeGroup>
  ```text Analytics theme={null}
  "Show me my analytics overview"
  "What's my success rate this week?"
  "How many active sessions do I have?"
  ```

  ```text Errors theme={null}
  "Show me all errors from yesterday"
  "Find errors with 'timeout' in the message"
  "Which tool has the most errors?"
  ```

  ```text Performance theme={null}
  "What were the slowest queries today?"
  "Show me tool calls over 1 second"
  "Find performance regressions this week"
  ```

  ```text Sessions theme={null}
  "Show me session abc123"
  "What happened in the last failed session?"
  "Get details for session xyz789"
  ```

  ```text Cost Optimization theme={null}
  "Which sessions have redundant tool calls?"
  "Show me the biggest batching opportunity"
  "How much money could I save by optimizing?"
  "Compare GPT-4 vs Claude Sonnet costs"
  ```
</CodeGroup>

## 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

<CardGroup cols={2}>
  <Card title="Claude Desktop Setup" icon="download" href="/claude-desktop-setup">
    Install and configure the MCP server
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Complete API documentation with examples
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Start tracking events in 5 minutes
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/gamladz/surfa-mcp">
    View source code and contribute
  </Card>
</CardGroup>