Respan MCP Server

Model Context Protocol (MCP) Server für Respan – greifen Sie direkt von Ihrem KI-Assistenten auf Logs, Prompts, Traces und Kundendaten zu.

Funktionen

• Logs – LLM-Anfragenprotokolle abfragen, filtern und erstellen

• Traces – Vollständige Ausführungs-Traces mit Span-Bäumen anzeigen

• Customers – Kundendaten und Budgetinformationen abrufen

• Prompts – Prompt-Vorlagen und -Versionen verwalten

Related MCP server: MCP Datadog Server

Schnellstart

Option 1: Öffentlicher HTTP (Empfohlen)

Keine Installation erforderlich.

1. Holen Sie sich Ihren API-Schlüssel von platform.respan.ai

2. Fügen Sie ihn zu Ihrer MCP-Konfigurationsdatei hinzu:

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "respan": {
      "url": "https://mcp.respan.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    }
  }
}

Claude Desktop (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "respan": {
      "url": "https://mcp.respan.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    }
  }
}

3. Starten Sie Cursor/Claude Desktop neu.

Option 2: Lokaler Stdio

Führen Sie den MCP-Server lokal für die persönliche Entwicklung oder Offline-Nutzung aus.

Voraussetzungen: Node.js v18+

git clone https://github.com/respanai/respan-mcp.git
cd respan-mcp
npm install
npm run build

{
  "mcpServers": {
    "respan": {
      "command": "node",
      "args": ["/absolute/path/to/respan-mcp/dist/lib/index.js"],
      "env": {
        "RESPAN_API_KEY": "YOUR_RESPAN_API_KEY"
      }
    }
  }
}

Option 3: Privater HTTP (Teams)

Stellen Sie Ihre eigene Instanz auf Vercel bereit, damit Teams eine einzelne Bereitstellung gemeinsam nutzen können.

Setzen Sie RESPAN_API_KEY im Vercel-Dashboard unter Einstellungen > Umgebungsvariablen.

Teilen Sie diese Konfiguration mit Ihrem Team:

{
  "mcpServers": {
    "respan": {
      "url": "https://your-project.vercel.app/mcp"
    }
  }
}

Verfügbare Werkzeuge

Organisationen

Alle anderen Werkzeuge lesen und schreiben nur die aktive Organisation. Das Wechseln ist kontoweit und dauerhaft – es verschiebt die Respan-Web-App und jede andere Sitzung in dieselbe Organisation, da das Backend die aktive Organisation im Benutzerdatensatz und nicht im Token speichert. Erfordert eine OAuth-Anmeldung; ein API-Schlüssel ist bereits an eine Organisation gebunden und kann nicht wechseln.

Protokolle

Traces

Kunden

Prompts

Workflows

Die Backend-Route wird gemeinsam genutzt, aber die MCP-Erstellungsfunktionen sind absichtlich getrennt. Automatisierungen sind ereignisgesteuerte Aufgabenpipelines und erhalten das dashboard-kompatible auto-sampling-Gate; Monitore akzeptieren Aggregations-, Bedingungs- und Bereitstellungsaufgaben und erfordern eine Benachrichtigung oder einen Webhook; Exporte akzeptieren einen UTC-Fünf-Feld-Cron plus exportspezifische Filter, Felder, Inline-Ergebnisverhalten und Sampling.

Filtersyntax

Werkzeuge, die Filtern unterstützen, akzeptieren ein filters-Objekt:

{
  "cost": {"operator": "gt", "value": [0.01]},
  "model": {"operator": "", "value": ["gpt-4"]},
  "customer_identifier": {"operator": "contains", "value": ["user"]},
  "metadata__session_id": {"operator": "", "value": ["abc123"]}
}

Operatoren: "" (gleich), not, lt, lte, gt, gte, contains, icontains, startswith, endswith, in, isnull

Projektstruktur

respan-mcp/
├── api/
│   └── mcp.ts                # HTTP entry point (Vercel serverless function)
├── lib/
│   ├── index.ts              # Stdio entry point (local mode)
│   ├── shared/
│   │   └── client.ts         # API client, auth config, path validation
│   ├── observe/
│   │   ├── logs.ts           # list_logs, get_log_detail, create_log
│   │   ├── traces.ts         # list_traces, get_trace_tree
│   │   └── users.ts          # list_customers, get_customer_detail
│   ├── account/
│   │   └── organizations.ts  # list_organizations, switch_organization
│   └── develop/
│       └── prompts.ts        # list_prompts, get_prompt_detail, versions
├── vercel.json               # Vercel config (rewrites, function timeout)
├── tsconfig.json             # TypeScript config
└── package.json

Architektur

• Zwei Einstiegspunkte: api/mcp.ts (HTTP über Vercel) und lib/index.ts (stdio für lokale Nutzung)

• Gemeinsamer Kern: Beide Einstiegspunkte erstellen ein AuthConfig und übergeben es über Closures an dieselben Werkzeugregistrierungsfunktionen – kein globaler veränderlicher Zustand

• Werkzeugmodule: Nach Domäne organisiert (observe/ für Laufzeitdaten, develop/ für Prompt-Verwaltung)

• API-Client: lib/shared/client.ts behandelt alle Upstream-API-Aufrufe mit 30s Timeout, Pfadvalidierung und Authentifizierung

Unternehmenskonfiguration

Für benutzerdefinierte API-Endpunkte setzen Sie die Umgebungsvariable RESPAN_API_BASE_URL:

Stdio-Modus:

{
  "mcpServers": {
    "respan": {
      "command": "node",
      "args": ["/path/to/respan-mcp/dist/lib/index.js"],
      "env": {
        "RESPAN_API_KEY": "YOUR_API_KEY",
        "RESPAN_API_BASE_URL": "https://your-endpoint.example.com/api"
      }
    }
  }
}

Private Bereitstellung: Setzen Sie RESPAN_API_BASE_URL in den Vercel-Umgebungsvariablen.

Lokale Entwicklung

npm run build        # Compile TypeScript
npm run stdio        # Build and run in stdio mode

Lokaler OAuth-Broker

Das Repository enthält ein Vercel-unabhängiges HTTP-Testgerüst für die öffentlichen OAuth- und MCP-Routen. Es verwendet die vorhandenen lokalen Backend- und Redis-Dienste; es startet, startet neu oder löscht keinen der Dienste.

Erstellen Sie eine .env.local-Datei (von Git ignoriert):

OAUTH_SECRET=<locally-generated-random-secret-of-at-least-32-characters>
OAUTH_SESSION_STORE=redis
REDIS_URL=redis://127.0.0.1:6379/15
MCP_REDIS_KEY_PREFIX=respan-mcp:local:
MCP_PUBLIC_BASE_URL=http://127.0.0.1:3100
MCP_ACCESS_TOKEN_TTL_SECONDS=60
RESPAN_API_BASE_URL=http://127.0.0.1:8000/api
RESPAN_ENTERPRISE_API_BASE_URL=http://127.0.0.1:8000/api

# Used only by the complete local verification probe:
OAUTH_TEST_EMAIL=<local-test-account-email>
OAUTH_TEST_PASSWORD=<local-test-account-password>
# Required by the platform probe's API-key compatibility check.
OAUTH_TEST_API_KEY=<local-test-api-key>
# Optional; defaults to platform. Also accepts enterprise.
OAUTH_TEST_REALM=platform

Um denselben von Vercel verwendeten Upstash-REST-Adapter zu testen, ersetzen Sie die lokalen Redis-Einstellungen durch:

OAUTH_SESSION_STORE=upstash
UPSTASH_REDIS_REST_URL=<upstash-rest-url>
UPSTASH_REDIS_REST_TOKEN=<upstash-rest-token>

Behalten Sie das lokale Schlüsselpräfix getrennt von Preview und Production bei. Die Prüfung ersetzt es immer durch ein eindeutiges, pro Lauf generiertes Präfix und löscht nur diese Schlüssel.

Für manuelles Browsetesting führen Sie den lokalen Dienst aus:

npm run dev:oauth

Der automatisierte Verifizierungsbefehl startet sein eigenes isoliertes Broker-Testgerüst, führen Sie ihn daher ohne einen separaten dev:oauth-Prozess aus:

npm run verify:oauth:local

Um denselben Lebenszyklus durch die Unternehmensressource und das Backend zu testen, führen Sie aus:

OAUTH_TEST_REALM=enterprise npm run verify:oauth:local

Um zu überprüfen, dass die Refresh-Rotation eine absolute Refresh-Sitzungsfrist nicht verlängert, führen Sie die Prüfung mit einer kurzen lokalen Lebensdauer aus:

OAUTH_VERIFY_REFRESH_EXPIRY=true \
MCP_REFRESH_SESSION_TTL_SECONDS=180 \
npm run verify:oauth:local

Die Prüfung rotiert das Refresh-Token, nachdem das Access-Token abgelaufen ist, wartet drei Minuten nach der ursprünglichen Sitzungsausstellung und erwartet dann invalid_grant vom neuesten Refresh-Token. Diese Einstellung dient nur der lokalen Überprüfung.

Die Prüfung startet ihr eigenes isoliertes Testgerüst auf 127.0.0.1:3100, verwendet ein eindeutiges Redis-Schlüsselpräfix, gibt nur Schrittstatus und Dauer aus und entfernt nur Schlüssel unter diesem eindeutigen Präfix. Führen Sie dev:oauth nicht gleichzeitig auf demselben Port aus. Die Google-Anmeldung erfordert separat konfigurierte lokale Backend-Anmeldeinformationen; die deterministische automatisierte Suite deckt das Broker-Verhalten ohne diese ab.

Gehostete OAuth-Client-Registrierungen akzeptieren HTTPS-Callbacks und HTTP-Callbacks, die an Loopback gebunden sind – die literalen Adressen 127.0.0.1 und [::1] oder der Hostname localhost, den Claude Code und der MCP Inspector registrieren. Der Hostname-Abgleich ist exakt, daher sind localhost.attacker.example und sub.localhost kein Loopback. Andere HTTP-Hosts, ausführbare URL-Schemata, Anmeldeinformationen, Fragmente, doppelte Callbacks und übermäßig große Callback-Listen werden abgelehnt.

Vercel-Bereitstellungen erfordern Upstash anstelle des In-Memory-Stores. Produktions-öffentliche und Backend-URLs müssen HTTPS verwenden, und OAuth-Geheimnisse und Redis-Anmeldeinformationen dürfen nur über den Bereitstellungs-Geheimnisverwalter konfiguriert werden.

Für die vollständige Preview- und Production-Einrichtung, die Umgebungsvariablen-Matrix, die Vercel-Dienstkonfiguration, das Verifikations-Gate, die Überwachung und das Rollback-Verfahren siehe Public MCP OAuth Broker: Vercel Deployment Runbook.

Automatisierte Prüfungen:

npm test
TEST_REDIS_URL=redis://127.0.0.1:6379/15 npm test -- --run tests/redis-store.integration.test.ts
npm run build
git diff --check

Dokumentation

Vollständige Dokumentation unter docs.respan.ai/documentation/resources/mcp

Lizenz

MIT