Spyglass-AI/spyglass-mcp

Spyglass AI MCP Server

The Spyglass AI MCP server provides a simple interface for LLMs to query the Spyglass AI agent. The agent analyzes your telemetry data and provides intelligent insights about application performance, errors, and bottlenecks.

To install the MCP server for Cursor click the button below. It should open Cursor and prompt you to add your API Key.

Alternatively, add the following to your ~/.cursor/mcp.json file (create it if you need to) and substitute your Spyglass API Key. Then restart Cursor to apply the change.

{
  "mcpServers": {
    "spyglass-ai": {
      "command": "uvx",
      "args": ["spyglass-mcp"],
      "env": {
        "SPYGLASS_API_KEY": "your-key-here"
      }
    }
  }
}

Note that you need to have uv installed first, see the docs for that here

Available Tools

call_spyglass_agent

Calls the Spyglass AI agent with a natural language query about your telemetry data.

Parameters:

• query (string, required): Natural language query about your application's telemetry data

Example queries:

• "What are the slowest endpoints in the last hour?"
• "Show me all errors in the checkout service"
• "Which services have the highest error rate?"
• "What's causing high latency in my API?"
• "How many requests has my app had in the last day?"

Returns:

• Natural language analysis of the telemetry data

Configuration

Environment Variables

Command Line Arguments

Example: Using with an MCP Client

import asyncio
from fastmcp import Client

client = Client("http://localhost:8000/mcp")

async def analyze():
    async with client:
        result = await client.call_tool("call_spyglass_agent", {
            "query": "What are the slowest endpoints?"
        })
        print(result)

asyncio.run(analyze())

Logging

The MCP server logs to both stderr (captured by Cursor) and a file for debugging:

Log file location:

~/.spyglass/logs/mcp-server-YYYYMMDD.log

View logs in real-time:

tail -f ~/.spyglass/logs/mcp-server-$(date +%Y%m%d).log

The logs include:

• Server startup and configuration
• Incoming queries and responses
• API call details (with truncated tokens for security)
• Error messages and stack traces

Development

Prerequisites

• Python 3.11 or higher
• uv package manager

Setup

1. Clone the repository and navigate to the project directory:

cd spyglass-mcp

2. Install dependencies:

uv sync

This will create a virtual environment and install all required dependencies.

3. Copy the example environment file and configure your API key:

cp env.example .env
# Edit .env and add your SPYGLASS_API_KEY

Running Locally

Run the MCP server in stdio mode (default):

uv run spyglass-mcp

Run with a custom endpoint (useful for testing against a local agent):

uv run spyglass-mcp --endpoint http://localhost:8080

Run in HTTP transport mode:

uv run spyglass-mcp --transport http --port 8000

Running Tests

Run all tests:

uv run pytest

Run tests with verbose output:

uv run pytest -v

Run a specific test file:

uv run pytest tests/test_mcp_server.py

Run tests with coverage:

uv run pytest --cov=spyglass_mcp --cov-report=term-missing

Building

Build the package for distribution:

uv build

This will create wheel and source distribution files in the dist/ directory.

Project Structure

spyglass-mcp/
├── .github/
│   └── workflows/
│       └── publish.yaml
├── src/
│   └── spyglass_mcp/
│       ├── __init__.py
│       └── main.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   └── test_mcp_server.py
├── CHANGELOG.md
├── env.example
├── LICENSE
├── pyproject.toml
├── README.md
└── uv.lock