Agent gateway documentation

How the agent gateway works

1. The developer fills in the registration and confirms their email.
2. The developer provides a public DPoP key (JWK or JWKS URL) during registration. After e-mail confirmation the system shows client_id and client_secret once.
3. The agent requests a token at agents.jobsai.cz/v1/oauth/token with a DPoP proof.
4. The MCP/A2A/ACP endpoints verify the DPoP token binding and separate candidate consent.

DPoP: the htu claim must equal the exact request URL. The nonce is optional - omit it, or echo the latest value from the DPoP-Nonce response header (a self-generated nonce is rejected). The authoritative token endpoint is in the OAuth metadata.

Idempotency: every write operation (MCP submit_application, withdraw_application, propose_action and execute_approved_action, ACP POST /runs and /runs/{id}/cancel) requires an Idempotency-Key header (UUID or an 8-255 char [a-zA-Z0-9_-] token). Without it the API returns 400 idempotency_key_required. Streaming tools (subscribe, stream_matches) return only a pointer via tools/call - open the stream itself with a second request using Accept: text/event-stream.

Quickstart: connect an MCP client

From zero to the first call in 3 steps. The server runs at agents.jobsai.cz (streamable HTTP); read tools need a registered agent, writes additionally need a candidate consent envelope.

1. Register your agent

The agent registration page issues a client_id and client_secret (shown once). Tokens come from the OAuth 2.1 client credentials flow with RFC 8414 discovery (links below).

2. Add the server to your client

Claude Desktop and compatible clients: add to your mcpServers configuration:

{
  "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. Make your first call

Once connected, the client loads tools/list. Start with search_jobs (live listings search) and get_job (detail). Write tools require a consent envelope - the candidate grants it in the Agent access section of their account.

Tools overview

Actions the candidate confirms

The propose_action, get_action_proposal and execute_approved_action tools form the confirmation loop. The agent only proposes an action; the candidate sees the exact command in their JobsAI account (agent access, approvals section), may edit it and confirm it, and only then does the agent execute exactly that command, once. The long-lived consent envelope does not replace that confirmation. The required scope is the scope of the proposed action and must be present both in the token and in the envelope. The feature is available only where the operator enabled it; elsewhere the tools return approvals_unavailable.

Example prompts

• 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.

The server is also listed in the official MCP registry as cz.jobsai/jobsai.