MCP-сервер

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

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

Є два способи підключитися:

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

Обидва ведуть до тих самих інструментів з тими самими обмеженнями. Сервер працює через Streamable HTTP.

Відкрийте Settings → Connectors (у новіших версіях — Customize → Connectors) і додайте custom connector.
Назвіть його Railhook і вкажіть URL https://railhook.io/mcp. OAuth Client ID і 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 і те, що вхід застосунок бере на себе.

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

Будь-який учасник організації може підключити застосунок лише на читання. Читання й запис потребує ролі Owner або Developer — тих самих ролей, що можуть створювати API-ключі. Підключений застосунок працює, лише доки людина, яка його дозволила, могла б дозволити це й сьогодні: якщо її видалити чи призупинити або знизити з Developer до Viewer, підключені нею застосунки перестануть працювати.

Застосунок отримує токен доступу на годину й сам його поновлює, тож працює, доки його не відключать.

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

Підключені до проєкту застосунки показано на сторінці 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-ключів і вимикає вхід. Див. Конфігурація.

Інструменти

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

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

Інструменти читання позначено підказкою read-only, за якою клієнт може запускати їх, не питаючи вас щоразу. Ендпоінти, підписки, доставки й спроби повертаються у формі, описаній у довіднику API, тіла спроб обрізаються до 2 000 символів; список повертається як 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`

Що далі

АвтентифікаціяAPI-ключі, їхні області доступу й ротація без простою.

Повторні спроби та невдалі повідомленняЩо бачить агент, коли доставка не вдається.

SDKНадсилайте події з коду.