Respan MCP Server

Сервер Model Context Protocol (MCP) для Respan — доступ к логам, промптам, трейсам и данным клиентов непосредственно из вашего AI-ассистента.

Возможности

• Логи — запрашивайте, фильтруйте и создавайте логи запросов LLM

• Трейсы — просматривайте полные трассировки выполнения с деревьями спанов

• Клиенты — получайте доступ к данным клиентов и информации о бюджете

• Промпты — управляйте шаблонами промптов и их версиями

Related MCP server: MCP Datadog Server

Быстрый старт

Вариант 1: Публичный HTTP (рекомендуется)

Установка не требуется.

1. Получите ваш API-ключ на platform.respan.ai

2. Добавьте в ваш конфигурационный файл MCP:

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. Перезапустите Cursor/Claude Desktop

Вариант 2: Локальный Stdio

Запустите MCP-сервер локально для личной разработки или офлайн-использования.

Предварительные требования: 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"
      }
    }
  }
}

Вариант 3: Частный HTTP (для команд)

Разверните собственный экземпляр на Vercel для команд, использующих одно развертывание.

Установите RESPAN_API_KEY в панели управления Vercel > Settings > Environment Variables.

Поделитесь этой конфигурацией с вашей командой:

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

Доступные инструменты

Организации

Все остальные инструменты читают и записывают только активную организацию. Переключение действует на всю учетную запись и является постоянным — оно перемещает веб-приложение Respan и любые другие сессии в ту же организацию, поскольку бэкенд хранит активную организацию в записи пользователя, а не в токене. Требуется вход через OAuth; API-ключ уже привязан к одной организации и не может переключаться.

Логи

Трейсы

Клиенты

Промпты

Рабочие процессы

Бэкенд-маршрут общий, но функции создания MCP намеренно разделены. Автоматизации — это конвейеры задач, управляемые событиями, и они получают совместимый с панелью управления шлюз auto-sampling; мониторы принимают задачи агрегации, условия и доставки и требуют уведомления или вебхука; экспорты принимают cron с пятью полями UTC, а также фильтры, поля, поведение встроенных результатов и выборку, специфичные для экспорта.

Синтаксис фильтров

Инструменты, поддерживающие фильтрацию, принимают объект filters:

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

Операторы: "" (равно), not, lt, lte, gt, gte, contains, icontains, startswith, endswith, in, isnull

Структура проекта

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

Архитектура

• Две точки входа: api/mcp.ts (HTTP через Vercel) и lib/index.ts (stdio для локального использования)

• Общее ядро: Обе точки входа создают AuthConfig и передают его одним и тем же функциям регистрации инструментов через замыкания — без глобального изменяемого состояния

• Модули инструментов: Организованы по доменам (observe/ для данных времени выполнения, develop/ для управления промптами)

• API-клиент: lib/shared/client.ts обрабатывает все вызовы вышестоящего API с таймаутом 30 секунд, проверкой пути и аутентификацией

Корпоративная конфигурация

Для пользовательских конечных точек API установите переменную окружения RESPAN_API_BASE_URL:

Режим Stdio:

{
  "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"
      }
    }
  }
}

Частное развертывание: Установите RESPAN_API_BASE_URL в переменных окружения Vercel.

Локальная разработка

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

Локальный OAuth-брокер

Репозиторий включает независимую от Vercel HTTP-обвязку для публичных маршрутов OAuth и MCP. Она использует существующие локальные бэкенд и Redis-сервисы; она не запускает, не перезапускает и не очищает ни один из сервисов.

Создайте игнорируемый git файл .env.local:

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

Чтобы задействовать тот же REST-адаптер Upstash, который используется Vercel, замените локальные настройки Redis на:

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

Держите локальный префикс ключей отличным от Preview и Production. Зонд всегда заменяет его на уникальный префикс для каждого запуска и удаляет только эти ключи.

Для ручного тестирования в браузере запустите локальный сервис:

npm run dev:oauth

Команда автоматической проверки запускает собственную изолированную обвязку брокера, поэтому запускайте её без отдельного процесса dev:oauth:

npm run verify:oauth:local

Чтобы задействовать тот же жизненный цикл через корпоративный ресурс и бэкенд, выполните:

OAUTH_TEST_REALM=enterprise npm run verify:oauth:local

Чтобы проверить, что ротация обновления не продлевает абсолютный срок сессии обновления, запустите зонд с коротким локальным временем жизни:

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

Зонд ротирует токен обновления после истечения токена доступа, ждет до трех минут с момента первоначальной выдачи сессии, а затем требует invalid_grant от последнего токена обновления. Эта настройка предназначена только для локальной проверки.

Зонд запускает собственную изолированную обвязку на 127.0.0.1:3100, использует уникальный префикс ключей Redis, выводит только статус шага и продолжительность и удаляет только ключи под этим уникальным префиксом. Не запускайте dev:oauth одновременно на том же порту. Вход через Google требует отдельно настроенных локальных учетных данных бэкенда; детерминированный автоматизированный набор покрывает поведение брокера без них.

Регистрации клиентов размещенного OAuth принимают HTTPS-колбэки и HTTP-колбэки, привязанные к loopback — буквальные адреса 127.0.0.1 и [::1] или имя хоста localhost, которое регистрируют Claude Code и MCP Inspector. Совпадение имени хоста точное, поэтому localhost.attacker.example и sub.localhost не являются loopback. Другие HTTP-хосты, исполняемые схемы URL, учетные данные, фрагменты, дублирующиеся колбэки и слишком большие списки колбэков отклоняются.

Развертывания Vercel требуют Upstash вместо хранилища в памяти. Публичные и бэкенд URL в продакшене должны использовать HTTPS, а секреты OAuth и учетные данные Redis должны настраиваться только через менеджер секретов развертывания.

Полную настройку Preview и Production, матрицу переменных окружения, конфигурацию сервисов Vercel, шлюз проверки, мониторинг и процедуру отката см. в Public MCP OAuth Broker: Vercel Deployment Runbook.

Автоматические проверки:

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

Документация

Полная документация на docs.respan.ai/documentation/resources/mcp

Лицензия

MIT