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

# Quickstart

> Get Surfa running in 5 minutes

Get Surfa up and running in 5 minutes. This guide will walk you through installing the SDK, tracking your first events, and querying them with Claude Desktop.

## Prerequisites

* Python 3.10 or higher
* A Surfa account (sign up at [surfa.dev](https://surfa.dev))
* Your Surfa API key

## Step 1: Install the SDK

Install the Surfa SDK in your MCP server project:

```bash theme={null}
pip install surfa-ingest
```

Or with `uv`:

```bash theme={null}
uv pip install surfa-ingest
```

## Step 2: Track Your First Event

Add Surfa to your MCP server code:

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

# Initialize analytics client
analytics = SurfaClient(
    ingest_key=os.getenv("SURFA_INGEST_KEY"),
    api_url=os.getenv("SURFA_API_URL", "https://surfa-web.vercel.app")
)

# Set runtime info once at startup
analytics.set_runtime(
    provider="anthropic",
    model="claude-3-5-sonnet",
    mode="stdio"
)

# Track events throughout your code
analytics.track({
    "kind": "tool",
    "subtype": "call_completed",
    "tool_name": "search",
    "status": "success",
    "latency_ms": 245
})
```

<Tip>
  The SDK auto-captures `client_id` and `request_id` from MCP context when you pass `ctx` parameter. You don't need to extract them manually!
</Tip>

## Step 3: Configure Your API Key

Set your Surfa API key as an environment variable:

```bash theme={null}
export SURFA_INGEST_KEY=sk_live_your_key_here
export SURFA_API_URL=https://surfa-web.vercel.app
```

Or add to your `.env` file:

```bash theme={null}
SURFA_INGEST_KEY=sk_live_your_key_here
SURFA_API_URL=https://surfa-web.vercel.app
```

<Note>
  Get your API key from your [Surfa dashboard](https://surfa-web.vercel.app/dashboard).
</Note>

## Step 4: Run Your MCP Server

Start your MCP server and trigger some tool calls:

```bash theme={null}
# Example with FastMCP
uv run fastmcp run server.py
```

Events will be automatically tracked and sent to Surfa in real-time.

## Step 5: View Your Analytics

Go to your [Surfa dashboard](https://surfa-web.vercel.app/dashboard) to see:

* Total sessions
* Success rate
* Average execution time
* Event timeline
* Error tracking

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/surfa/images/dashboard-preview.png" alt="Surfa Dashboard" />
</Frame>

## Step 6: Test Your MCP Connection (Optional)

Want to validate your MCP is working correctly?

<Steps>
  <Step title="Navigate">
    Go to **Settings → MCP** in Surfa
  </Step>

  <Step title="Add MCP">
    Click **Add New MCP**
  </Step>

  <Step title="Configure">
    Enter your MCP details (endpoint, transport, headers)
  </Step>

  <Step title="Test">
    Click **Test Connection**
  </Step>

  <Step title="Success">
    See discovered tools ✅
  </Step>
</Steps>

<Card title="MCP Testing Guide" icon="plug" href="/mcp-testing" horizontal>
  Learn how to test and debug MCP connections
</Card>

## Next: Query with Natural Language (Optional)

Want to query your analytics by asking Claude questions in natural language?

<Card title="Set Up Surfa MCP Server" icon="sparkles" href="/mcp-server/claude-desktop-setup" horizontal>
  Install the Surfa MCP Server to query analytics through Claude Desktop
</Card>

**What you can do:**

* Ask "What's my success rate?" → Get instant answers
* "Find all errors from yesterday" → Filtered results
* "Analyze my product health" → AI-powered recommendations

**No dashboards. No SQL. Just conversation.**

## Example: Complete MCP Server

Here's a complete example of an MCP server with Surfa tracking:

```python theme={null}
from fastmcp import FastMCP, Context
from surfa_ingest import SurfaClient
import os

# Initialize analytics
analytics = SurfaClient(
    ingest_key=os.getenv("SURFA_INGEST_KEY"),
    api_url=os.getenv("SURFA_API_URL", "https://surfa-web.vercel.app")
)

# Set runtime info
analytics.set_runtime(
    provider="mcp",
    model="my-mcp-server",
    mode="stdio"
)

# Initialize MCP server
mcp = FastMCP("my-mcp-server")

@mcp.tool()
def search(query: str, ctx: Context) -> str:
    """Search for information."""
    
    # Track tool call start (ctx auto-extracts client_id, request_id)
    analytics.track({
        "kind": "tool",
        "subtype": "call_started",
        "tool_name": "search"
    }, ctx=ctx)
    
    try:
        # Your search logic here
        results = perform_search(query)
        
        # Track success
        analytics.track({
            "kind": "tool",
            "subtype": "call_completed",
            "tool_name": "search",
            "status": "success"
        }, ctx=ctx)
        analytics.flush()
        
        return results
        
    except Exception as e:
        # Track error
        analytics.track({
            "kind": "tool",
            "subtype": "call_failed",
            "tool_name": "search",
            "status": "error"
        }, ctx=ctx)
        analytics.flush()
        raise

if __name__ == "__main__":
    mcp.run()
```

## What's Tracked Automatically?

When you pass the `ctx` parameter, the Surfa SDK automatically extracts:

* ✅ **Client ID** - Identifies the MCP client (e.g., Claude Desktop) from MCP context
* ✅ **Request ID** - Tracks individual requests from MCP context
* ✅ **Timestamps** - When events occurred
* ✅ **Sequence Numbers** - Event ordering within a session
* ✅ **Runtime Metadata** - Provider, model, mode (via `set_runtime()`)

You need to provide:

* **kind** - Event kind (e.g., "tool", "session", "runtime")
* **subtype** - Event subtype (e.g., "call\_started", "call\_completed")
* **tool\_name** - Name of the tool being called
* **Custom fields** - Status, latency, error messages, etc.

## Next Steps

<CardGroup cols={2}>
  <Card title="Track Events" icon="code" href="/sdk/track-events">
    Learn how to track different types of events
  </Card>

  <Card title="Claude Desktop Setup" icon="sparkles" href="/mcp-server/claude-desktop-setup">
    Full guide to setting up Claude Desktop integration
  </Card>

  <Card title="Available Tools" icon="wrench" href="/mcp-server/available-tools">
    Explore all MCP server tools for querying analytics
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/guides/best-practices">
    Tips for getting the most out of Surfa
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events not showing up in dashboard" icon="circle-exclamation">
    **Check:**

    * API key is correct (`SURFA_INGEST_KEY`)
    * API URL is set (`SURFA_API_URL`)
    * Your MCP server is actually running
    * No firewall blocking outbound requests

    **Debug:**

    ```python theme={null}
    import logging
    logging.basicConfig(level=logging.DEBUG)
    ```
  </Accordion>

  <Accordion title="Claude Desktop not showing Surfa MCP" icon="circle-exclamation">
    **Check:**

    * Config file path is correct
    * JSON syntax is valid (no trailing commas)
    * `uv` path is correct (run `which uv` to find it)
    * Surfa MCP directory path is absolute, not relative

    **Debug:**
    Check Claude Desktop logs:

    ```bash theme={null}
    tail -f ~/Library/Logs/Claude/mcp*.log
    ```
  </Accordion>

  <Accordion title="Import error: No module named 'surfa_ingest'" icon="circle-exclamation">
    **Solution:**
    Make sure you installed the SDK in the correct environment:

    ```bash theme={null}
    pip install surfa-ingest
    # or
    uv pip install surfa-ingest
    ```

    Verify installation:

    ```bash theme={null}
    pip list | grep surfa
    ```
  </Accordion>
</AccordionGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="View Documentation" icon="book" href="/getting-started/introduction">
    Browse the full documentation
  </Card>

  <Card title="Join Discord" icon="discord" href="https://discord.gg/surfa">
    Get help from the community
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/gamladz/surfa-mcp/issues">
    Report bugs or request features
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@surfa.dev">
    Contact our support team
  </Card>
</CardGroup>