Shepherd MCP¶

Debug your AI agents like you debug your code.

Shepherd MCP is a Model Context Protocol (MCP) server that allows AI assistants (Claude, Cursor, etc.) to query and analyze your AI agent sessions from multiple observability providers.

Quick Start¶

Installation¶

Install via pip:

pip install shepherd-mcp

Or run directly with uvx (no installation required):

uvx shepherd-mcp

Configuration¶

Set your environment variables based on your observability provider:

AIOBS (Shepherd)

export AIOBS_API_KEY=aiobs_sk_xxxx

Langfuse

export LANGFUSE_PUBLIC_KEY=pk-lf-xxxx
export LANGFUSE_SECRET_KEY=sk-lf-xxxx
export LANGFUSE_HOST=https://cloud.langfuse.com

Supported Providers¶

Shepherd MCP supports multiple observability providers:

Provider	Description	Status
AIOBS (Shepherd)	Native Shepherd observability backend with deep insights	✅ Full Support
Langfuse	Open-source LLM observability platform	✅ Full Support

AIOBS (Shepherd)¶

Native Shepherd observability backend. Provides deep insights into your AI agent sessions including LLM calls, function events, and evaluations.

Required Environment Variables:

AIOBS_API_KEY — Your Shepherd API key

Optional Environment Variables:

AIOBS_ENDPOINT — Custom API endpoint URL

Langfuse¶

Open-source LLM observability platform. Supports traces, observations, sessions, and scores.

Required Environment Variables:

LANGFUSE_PUBLIC_KEY — Your Langfuse public API key
LANGFUSE_SECRET_KEY — Your Langfuse secret API key

Optional Environment Variables:

LANGFUSE_HOST — Custom Langfuse host URL (defaults to cloud.langfuse.com)

Integration¶

Claude Desktop¶

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "shepherd": {
      "command": "uvx",
      "args": ["shepherd-mcp"],
      "env": {
        "AIOBS_API_KEY": "aiobs_sk_xxxx",
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxxx"
      }
    }
  }
}

Cursor¶

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "shepherd": {
      "command": "uvx",
      "args": ["shepherd-mcp"],
      "env": {
        "AIOBS_API_KEY": "aiobs_sk_xxxx",
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxxx"
      }
    }
  }
}

📖 User Guide

Learn about available MCP tools and how to use them effectively.

Available Tools

💡 Use Cases

Explore real-world examples and debugging workflows.

Use Cases

📚 API Reference

Detailed documentation of providers, models, and interfaces.

Providers API Reference

🛠️ Development

Contributing guidelines and development setup.

Development Guide