Документація agent gateway

Як працює agent gateway

1. Розробник заповнює реєстрацію і підтверджує електронну пошту.
2. Розробник під час реєстрації вказує публічний DPoP-ключ (JWK або JWKS URL). Після підтвердження e-mail система одноразово показує client_id і client_secret.
3. Агент запитує токен на agents.jobsai.cz/v1/oauth/token з DPoP-доказом.
4. MCP/A2A/ACP ендпоінти перевіряють DPoP-прив'язку токена та окрему згоду кандидата.

DPoP: claim htu має дорівнювати точній URL запиту. Nonce необов'язкова - пропустіть її або використайте останнє значення з заголовка відповіді DPoP-Nonce (самостійно згенерована nonce буде відхилена). Авторитетний токен-ендпоінт вказано в OAuth метаданих.

Ідемпотентність: кожна операція запису (MCP submit_application, withdraw_application, propose_action і execute_approved_action, ACP POST /runs і /runs/{id}/cancel) вимагає заголовка Idempotency-Key (UUID або токен 8-255 символів [a-zA-Z0-9_-]). Без нього API повертає 400 idempotency_key_required. Стрімінгові інструменти (subscribe, stream_matches) через tools/call повертають лише вказівник - сам потік відкрийте другим запитом з Accept: text/event-stream.

Quickstart: підключіть MCP-клієнт

Від нуля до першого виклику за 3 кроки. Сервер працює на agents.jobsai.cz (streamable HTTP); інструменти читання потребують зареєстрованого агента, запис - додатково конверта згоди кандидата.

1. Зареєструйте агента

Сторінка реєстрації агента видає client_id і client_secret (показуються один раз). Токени видає OAuth 2.1 client credentials flow з discovery за RFC 8414 (посилання нижче).

2. Додайте сервер у клієнт

Claude Desktop і сумісні клієнти: додайте до конфігурації mcpServers:

{
  "mcpServers": {
    "jobsai": {
      "type": "http",
      "url": "https://agents.jobsai.cz/v1/mcp"
    }
  }
}

Claude Code (CLI):

claude mcp add --transport http jobsai https://agents.jobsai.cz/v1/mcp

3. Зробіть перший виклик

Після підключення клієнт завантажує tools/list. Почніть із search_jobs (пошук актуальних вакансій) і get_job (деталі). Інструменти запису потребують конверта згоди - кандидат надає його в розділі Агентний доступ свого акаунта.

Огляд інструментів

Дії, які підтверджує кандидат

Інструменти propose_action, get_action_proposal і execute_approved_action утворюють цикл підтвердження. Агент лише пропонує дію; кандидат бачить точний текст команди у своєму обліковому записі JobsAI (агентний доступ, розділ підтверджень), може змінити її та підтвердити, і лише після цього агент виконує саме цю команду, один раз. Довгострокова згода не замінює це підтвердження. Потрібний scope - це scope запропонованої дії, і він має бути і в токені, і в згоді. Функція доступна лише там, де оператор її увімкнув; в інших середовищах інструменти повертають approvals_unavailable.

Приклади промптів

• Find 5 open cook positions in Prague on JobsAI and compare their salary ranges.
• Get the details of JobsAI job <id> and summarize the requirements in Czech.
• With my JobsAI consent envelope, apply to job <id> and then check the application status.

Сервер також є в офіційному MCP registry під іменем cz.jobsai/jobsai.