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

# Introduction

> Observability for AI Agents and MCP Servers

## What is Surfa?

Surfa is the easiest way to understand what's happening inside your AI agents and MCP servers.

**Stop debugging logs. Start asking questions.**

Instead of digging through scattered logs, just ask Claude:

* "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.

## The Problem

Building AI agents? You're probably:

* 🔍 **Debugging scattered logs** across multiple tools
* 📊 **Manually tracking metrics** in spreadsheets
* ❓ **Guessing why tools fail** without visibility
* ⏰ **Wasting hours** investigating issues

## The Solution

Add a few lines of code. Get instant insights.

```python theme={null}
from surfa_ingest import SurfaClient

analytics = SurfaClient(ingest_key="sk_live_...")
analytics.track({
    "kind": "tool",
    "subtype": "call_completed",
    "tool_name": "search",
    "status": "success"
})
```

Then ask Claude: **"Show me my analytics overview"** → Get instant answers with real data.

## How It Works

<Steps>
  <Step title="Instrument">
    Add the Surfa SDK to your MCP server (2 lines of code)
  </Step>

  <Step title="Track">
    Events are auto-captured in real-time to your dashboard
  </Step>

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

  <Step title="Insights">
    Get AI-powered analysis, recommendations, and alerts
  </Step>
</Steps>

## Quick Start

<CardGroup cols={2}>
  <Card title="5-Minute Quickstart" icon="rocket" href="/quickstart">
    Get Surfa running in 5 minutes with our step-by-step guide.
  </Card>

  <Card title="Claude Desktop Setup" icon="sparkles" href="/claude-desktop-setup">
    Query your analytics with natural language through Claude.
  </Card>
</CardGroup>

## Two Products

<CardGroup cols={2}>
  <Card title="Surfa SDK" icon="code" href="/quickstart">
    Track events from your MCP server. Auto-capture sessions, latency, errors, and runtime metadata.
  </Card>

  <Card title="Surfa MCP Server" icon="messages-question" href="/mcp-server-overview">
    Query your analytics with natural language through Claude Desktop. No dashboards needed.
  </Card>
</CardGroup>

## Why Surfa?

<AccordionGroup>
  <Accordion title="Zero Setup" icon="bolt">
    No complex logging infrastructure. No data pipelines. Just add the SDK and you're done.
  </Accordion>

  <Accordion title="MCP-Native" icon="puzzle-piece">
    Built specifically for MCP patterns. Understands sessions, tools, and agent workflows out of the box.
  </Accordion>

  <Accordion title="Real-Time" icon="clock">
    Events appear in your dashboard instantly. No waiting for batch jobs or ETL.
  </Accordion>

  <Accordion title="AI-Powered" icon="brain">
    Ask questions in natural language. Get insights and recommendations from AI that understands your data.
  </Accordion>
</AccordionGroup>

## Perfect For

<CardGroup cols={3}>
  <Card title="Product Managers" icon="chart-line">
    Track adoption, success rates, and user behavior without SQL.
  </Card>

  <Card title="Developers" icon="code">
    Debug faster with session replay and error tracking.
  </Card>

  <Card title="DevOps Teams" icon="server">
    Monitor performance, latency, and uptime in real-time.
  </Card>
</CardGroup>

## Example Queries

See what you can ask Claude with the Surfa MCP Server:

<CodeGroup>
  ```text Analytics Overview theme={null}
  "Show me my analytics overview"
  ```

  ```text Error Investigation theme={null}
  "Show me all errors from the last 24 hours"
  ```

  ```text Performance Analysis theme={null}
  "What were the slowest queries this week?"
  ```

  ```text Session Deep-Dive theme={null}
  "Show me details for session abc123"
  ```
</CodeGroup>

**Response Format:**
All tools return JSON for easy parsing by AI agents:

```json theme={null}
{
  "ok": true,
  "data": {
    "totalSessions": 150,
    "successRate": 85,
    "avgExecutionTime": 245,
    "activeSessions": 12
  }
}
```

## Multi-Query Workflows

The PM Agent can chain queries together for complex analysis:

**Example workflow:**

1. **Get analytics** → sees low success rate (54%)
2. **Query events** with `status=error` → finds "Database unavailable" errors
3. **Analyze patterns** → identifies Feb 21-22 outage
4. **Provide recommendations** → Add health checks, circuit breakers

**All in seconds. No dashboards. No SQL.**

## Ready to Start?

<Card title="Get Started Now" icon="rocket" href="/quickstart" horizontal>
  Follow our quickstart guide and be up and running in 5 minutes.
</Card>

***

<CardGroup cols={2}>
  <Card title="View on GitHub" icon="github" href="https://github.com/gamladz/surfa-mcp">
    Star us on GitHub and contribute to the project.
  </Card>

  <Card title="Join Community" icon="discord" href="https://discord.gg/surfa">
    Get help, share feedback, and connect with other users.
  </Card>
</CardGroup>