MCP-сервер

Railhook має сервер Model Context Protocol за адресою /mcp. Підключений агент може з’ясувати, чому доставка не вдалася, відтворити її, зареєструвати ендпоінт чи надіслати тестову подію, в одному проєкті, з доступом лише на читання або на читання й запис.

Де	URL MCP-сервера
Railhook Cloud	`https://railhook.io/mcp`
Власний сервер	`<ваш origin>/mcp`, наприклад `https://hooks.example.com/mcp`

Wellknown, публічний каталог MCP-серверів, регулярно перевіряє хмарний сервер і публікує його доступність.

Два способи підключитися, з тими самими інструментами й обмеженнями. Транспорт: Streamable HTTP.

Вхід в обліковий запис. claude.ai, конектори Claude Desktop і ChatGPT перенаправляють вас у Railhook, щоб ви надали їм доступ до проєкту.
API-ключ проєкту. Claude Code, Cursor і stdio-міст @railhook/mcp надсилають ключ у заголовку.

Відкрийте Settings → Connectors (у новіших версіях Customize → Connectors) і додайте custom connector.
Назвіть його Railhook і вкажіть URL https://railhook.io/mcp. Поля OAuth Client ID і Client Secret залиште порожніми: Claude зареєструється сам.
Натисніть Connect. Відкриється Railhook; увійдіть, якщо ще не ввійшли.
Виберіть організацію та проєкт, рівень доступу Лише читання або Читання й запис і натисніть Підключити. Після цього вас поверне в Claude.

Конектор, доданий на claude.ai, працює також у Claude Desktop і мобільних застосунках, де ви ввійшли в той самий обліковий запис.

Увімкніть режим розробника: Settings → Apps → Advanced settings → Developer mode. У робочому просторі Business чи Enterprise, можливо, адміністратору доведеться спершу дозволити користувацькі конектори.
Створіть конектор з URL https://railhook.io/mcp і автентифікацією OAuth.
ChatGPT відкриє Railhook. Увійдіть, виберіть організацію, проєкт і рівень доступу та натисніть Підключити.

Підключення дає те саме, що API-ключ: один проєкт і один рівень доступу. Застосунок, підключений лише на читання, не надішле подію й не відтворить доставку. Меню вище змінюються між версіями застосунків, URL лишається тим самим.

Хто що може підключити

Будь-який учасник організації може підключити застосунок лише на читання. Для читання й запису потрібна роль «Власник» або «Розробник», ті самі ролі, що можуть створювати API-ключі. Підключений застосунок працює, лише доки людина, яка його підключила, могла б зробити це й зараз: якщо її видалити, призупинити або понизити з «Розробника» до «Спостерігача», її застосунки перестануть працювати.

Токен доступу діє годину, застосунок оновлює його сам.

Перегляд і відключення застосунків

Підключені до проєкту застосунки перелічено на сторінці «API-ключі», під ключами. Для кожного видно рівень доступу, хост, з якого він увійшов, хто його підключив і коли ним востаннє користувалися. Кнопка «Відключити» одразу припиняє доступ. Підключення й відключення записуються в журнал аудиту організації.

Підключення з API-ключем

claude mcp add --transport http railhook https://railhook.io/mcp \
  --header "Authorization: Bearer $RAILHOOK_API_KEY"

Додайте --scope user, щоб сервер був доступний у кожному проєкті. claude mcp list покаже, чи вдалося підключитися.

{
  "mcpServers": {
    "railhook": {
      "url": "https://railhook.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:RAILHOOK_API_KEY}"
      }
    }
  }
}

~/.cursor/mcp.json робить сервер доступним у кожному проєкті. ${env:RAILHOOK_API_KEY} береться зі змінних середовища Cursor, тож ключ не потрапляє у файл.

Сервери з файлу конфігурації Claude Desktop є локальними процесами, тому вони працюють через міст. Для нього потрібен Node.js 18 або новіший. Щоб натомість підключитися через вхід, додайте конектор, як описано вище.

{
  "mcpServers": {
    "railhook": {
      "command": "npx",
      "args": ["-y", "@railhook/mcp"],
      "env": {
        "RAILHOOK_API_KEY": "your-project-api-key"
      }
    }
  }
}

Відкрийте файл через Settings → Developer → Edit Config, потім перезапустіть Claude Desktop.

Клієнту з підтримкою віддалених серверів потрібні URL і один заголовок, будь-який із двох:

Authorization: Bearer <project API key>
X-API-Key: <project API key>

Клієнт, що вміє лише запускати локальні процеси, натомість запускає міст:

RAILHOOK_API_KEY=<project API key> npx -y @railhook/mcp

Власний сервер

Замініть у URL https://railhook.io на origin вашого інстансу. Для моста задайте RAILHOOK_BASE_URL поруч із ключем:

"env": {
  "RAILHOOK_API_KEY": "your-project-api-key",
  "RAILHOOK_BASE_URL": "https://hooks.example.com"
}

Для входу потрібні дві умови. APP_BASE_URL має бути публічним HTTPS-origin, бо застосунок перенаправляє туди й перевіряє його як issuer. І інстанс має бути доступний з інтернету, бо claude.ai і ChatGPT під’єднуються зі своїх серверів. Інстанс у приватній мережі приймає лише API-ключі.

Обидва перемикачі типово ввімкнено. MCP_ENABLED=false у .env вимикає /mcp; MCP_OAUTH_ENABLED=false лишає його для API-ключів, але вимикає вхід. Див. Конфігурація.

Інструменти

Кожен інструмент діє в проєкті ключа чи підключеного застосунку. Жоден не приймає ідентифікатор проєкту, тож агент не дістанеться до іншого проєкту, навіть у тій самій організації.

Інструмент	Що робить	Доступ
`list_endpoints`	Ендпоінти проєкту: чи ввімкнено й чи перевірено кожен	Будь-який
`list_subscriptions`	Який ендпоінт отримує який тип подій; можна обмежити одним ендпоінтом	Будь-який
`list_deliveries`	Доставки від найновіших, з фільтрами за статусом, ендпоінтом, подією, типом події чи часом	Будь-який
`get_delivery`	Одна доставка й усі її спроби: код статусу, помилка, тривалість, тіла запиту й відповіді	Будь-який
`send_event`	Надсилає подію; на кожну ввімкнену підписку на її тип Railhook створює одну доставку	`READ_WRITE`
`create_endpoint`	Реєструє ендпоінт і один раз повертає його секрет підпису	`READ_WRITE`
`create_subscription`	Підписує ендпоінт на тип подій	`READ_WRITE`
`replay_delivery`	Повертає доставку зі статусом `FAILED` чи `DLQ` у її розклад повторних спроб; `dryRun` показує, що буде надіслано	`READ_WRITE`

Інструменти читання мають підказку read-only, тож клієнт може запускати їх, не питаючи. Результати мають структуру з довідника API, тіла спроб обрізаються до 2000 символів. Список повертається як content разом із page, size, totalElements і totalPages.

Діють обмеження API: send_event зараховується в ліміт запитів і квоту подій проєкту, create_endpoint у ліміт ендпоінтів.

Розв’язання проблем

Симптом	Що робити
`401` під час підключення клієнта з ключем	Ключ неправильний, відкликаний чи прострочений або належить не тому інстансу, на який указує URL. Створіть новий ключ
Застосунок знову просить увійти	Застосунок відключили, або людину, яка його підключила, видалили, призупинили чи позбавили потрібної ролі. Підключіть його знову
«Термін дії запиту минув» на екрані підтвердження	Екран був відкритий понад десять хвилин, або на запит уже відповіли. Почніть підключення заново із застосунку
«Цей застосунок не можна підключити»	Застосунок попросив повернути вас на адресу, якої не реєстрував. Видаліть конектор у застосунку й додайте його знову
Інструмент відповідає, що ключ чи застосунок має доступ лише на читання	Для інструментів запису це очікувано. Використайте ключ `READ_WRITE` або підключіть застосунок заново з доступом Читання й запис
`404` на `/mcp` чи `/.well-known/oauth-authorization-server` на власному сервері	`MCP_ENABLED` або `MCP_OAUTH_ENABLED` має значення `false`, або версія інстансу ще не підтримує цієї можливості. Оновіть його
Міст завершується з `RAILHOOK_API_KEY is not set`	Передайте ключ у блоці `env` конфігурації клієнта, а не в `args`