Agent gateway

Agent gateway documentation

The agent gateway is a separate domain at agents.jobsai.cz. Clients register on the main website, then obtain a DPoP-bound OAuth2 token via client-credentials.

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, or for company tools the company's authorization.

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, the company tools create_job_draft, update_job, update_job_terms, confirm_job_terms, publish_job, archive_job and confirm_job_open, 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, and company tools need the company's authorization.

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. Company tools require the company's authorization - an owner or admin issues it on the AI agents page of the company account.

Tools overview

ToolRequired access
search_jobsjobs:read
get_jobjobs:read
submit_applicationapplications:write + consent envelope
get_application_statusapplications:read + consent envelope
list_applicationsapplications:read + consent envelope
withdraw_applicationapplications:write + consent envelope
saved_jobsapplications:read/write + consent envelope
subscribe (SSE)applications:read + consent envelope
stream_matches (SSE)matches:read + consent envelope
propose_actionscope of the proposed action + consent envelope
get_action_proposalscope of the proposed action + consent envelope
execute_approved_actionscope of the proposed action + consent envelope
list_employer_jobsemployer_jobs:read + representation envelope
get_employer_jobemployer_jobs:read + representation envelope
list_employer_branchesemployer_jobs:read + representation envelope
create_job_draftemployer_jobs:write + representation envelope
update_jobemployer_jobs:write (live job: employer_jobs:publish) + representation envelope
update_job_termsemployer_jobs:write (live job: employer_jobs:publish) + representation envelope
confirm_job_termsemployer_jobs:write (live job: employer_jobs:publish) + representation envelope
publish_jobemployer_jobs:publish + representation envelope
archive_jobemployer_jobs:publish + representation envelope
confirm_job_openemployer_jobs:publish + representation envelope

In tools/list every tool carries MCP annotations: readOnlyHint on tools that only read, destructiveHint on tools that can remove, withdraw, cancel, hide or overwrite something, and idempotentHint where a repeated call changes nothing further. Clients use them to decide when to ask the user; the server still enforces access.

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.

Company agent

The tools list_employer_jobs, get_employer_job, list_employer_branches, create_job_draft, update_job, update_job_terms, confirm_job_terms, publish_job, archive_job and confirm_job_open manage the jobs of one company. The agent calls them with an authorization (representation envelope) that a company owner or admin issues on the AI agents page of the company account, and sends it with every call in the X-Jobsai-Representation-Envelope header next to the DPoP token. The required scope (employer_jobs:read, employer_jobs:write or employer_jobs:publish) must be in both the token and the authorization. The agent acts as the person who issued the authorization. An authorization is valid for 7, 30 or 90 days and the company can revoke it at any time.

  • Drafts (employer_jobs:read + employer_jobs:write): read the company's jobs and workplaces, create and edit job drafts and their conditions. A person from the company publishes.
  • Drafts and publishing (plus employer_jobs:publish): publish, edit live jobs, archive and confirm that a position is still open.

Only a verified company's job with a salary range can be published. Texts go through the anti-discrimination check and the agent cannot claim an exception. Every call is written to the activity log the company sees. Without an authorization the tools return representation_required, after revocation representation_revoked. Changes use an optimistic lock: update_job needs editHash and update_job_terms needs terms.revision from get_employer_job; a stale value returns facts_changed (reason stale_edit_hash or stale_terms_revision). Changing the title or description raises terms.revision and unconfirms the conditions, so read the job again before the next conditions change.

Help for companies: AI agents for companies

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.
  • With our company's JobsAI representation envelope, create a draft job for a warehouse worker in Brno with a salary range of 32000-38000 CZK per month.
  • List our company's active JobsAI jobs and confirm the ones that are still open.

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

Links

A machine-readable compliance summary (provider, risk category, human oversight, contact and data-subject rights) is available at /compliance.json.

The messages:write scope is reserved for a future messaging endpoint and is not issued in tokens yet.

Transparency and obligations for AI agent operators