Dokumentation des Agent-Gateways

Wie das Agent-Gateway funktioniert

1. Der Entwickler füllt die Registrierung aus und bestätigt die E-Mail-Adresse.
2. Der Entwickler gibt bei der Registrierung einen öffentlichen DPoP-Schlüssel an (JWK oder JWKS-URL). Nach der E-Mail-Bestätigung zeigt das System client_id und client_secret einmalig an.
3. Der Agent fordert ein Token unter agents.jobsai.cz/v1/oauth/token mit DPoP-Beweis an.
4. Die MCP/A2A/ACP-Endpunkte prüfen die DPoP-Token-Bindung und die separate Kandidatenzustimmung.

DPoP: Der htu-Claim muss der exakten Request-URL entsprechen. Die Nonce ist optional - lassen Sie sie weg oder verwenden Sie den letzten Wert aus dem DPoP-Nonce-Response-Header (eine selbst erzeugte Nonce wird abgelehnt). Der maßgebliche Token-Endpoint steht in den OAuth-Metadaten.

Idempotenz: Jede Schreiboperation (MCP submit_application, withdraw_application, propose_action und execute_approved_action, ACP POST /runs und /runs/{id}/cancel) erfordert einen Idempotency-Key-Header (UUID oder 8-255 Zeichen [a-zA-Z0-9_-]). Ohne ihn antwortet die API mit 400 idempotency_key_required. Streaming-Tools (subscribe, stream_matches) liefern über tools/call nur einen Verweis - den Stream selbst öffnen Sie mit einem zweiten Request mit Accept: text/event-stream.

Quickstart: MCP-Client verbinden

Von null zum ersten Aufruf in 3 Schritten. Der Server läuft auf agents.jobsai.cz (Streamable HTTP); Lese-Tools benötigen einen registrierten Agenten, Schreibzugriffe zusätzlich eine Einwilligungs-Envelope des Kandidaten.

1. Agent registrieren

Die Agenten-Registrierung stellt client_id und client_secret aus (einmalig angezeigt). Tokens kommen aus dem OAuth 2.1 Client-Credentials-Flow mit RFC 8414 Discovery (Links unten).

2. Server im Client hinzufügen

Claude Desktop und kompatible Clients: zur mcpServers-Konfiguration hinzufügen:

{
  "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. Ersten Aufruf machen

Nach der Verbindung lädt der Client tools/list. Beginnen Sie mit search_jobs (Suche in aktuellen Stellen) und get_job (Detail). Schreib-Tools erfordern eine Einwilligungs-Envelope - der Kandidat erteilt sie im Bereich Agentenzugriff seines Kontos.

Tool-Übersicht

Aktionen, die der Kandidat bestätigt

Die Tools propose_action, get_action_proposal und execute_approved_action bilden die Bestätigungsschleife. Der Agent schlägt eine Aktion nur vor; der Kandidat sieht den genauen Befehl in seinem JobsAI-Konto (Agentenzugriff, Bereich Freigaben), kann ihn bearbeiten und bestätigen, und erst danach führt der Agent genau diesen Befehl einmal aus. Die langfristige Zustimmungshülle ersetzt diese Bestätigung nicht. Der erforderliche Scope ist der Scope der vorgeschlagenen Aktion und muss sowohl im Token als auch in der Hülle vorhanden sein. Die Funktion ist nur dort verfügbar, wo der Betreiber sie aktiviert hat; andernfalls liefern die Tools approvals_unavailable.

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

Der Server ist auch im offiziellen MCP-Registry als cz.jobsai/jobsai gelistet.