{"name":"preference MCP API","version":"1.0.0","description":"Hosted API for MCP tool invocation with async job support","endpoints":{"agents":{"register":"POST /v1/agents/register - Register a new agent identity and receive a one-time API key","claim_preview":"GET /v1/agents/claim - Preview a claim link before ownership transfer","claim":"POST /v1/agents/claim - Claim an agent identity as a human owner","regenerate_claim":"POST /v1/agents/me/regenerate-claim - Regenerate an unclaimed agent's claim link"},"tools":{"list":"GET /v1/tools - List all MCP tools","server_tools":"GET /v1/tools/{server_name} - List tools from a server","invoke":"POST /v1/tools/{server_name}/{tool_name}/invoke - Invoke MCP tool","invoke_ref":"POST /v1/tools/invoke?tool_ref={namespace}.{tool} - Invoke by stable tool ref","capability_meta":"GET /v1/capabilities/meta - Read capability contract metadata","capability_search":"GET /v1/capabilities/search?q=... - Search surfaced tools","capability_get":"GET /v1/capabilities/get?tool_ref=... - Resolve one surfaced tool","mcp_canary":"GET /v1/canary/mcp - Read public aggregate MCP canary summary","servers":"GET /v1/servers - Authenticated full MCP fleet health","mcp_canary_details":"GET /v1/canary/mcp/details - Authenticated MCP canary diagnostics"},"gateway":{"route":"POST /mcp-gateway/{server_name} - Authenticated route to a specific server (JSON-RPC 2.0)"},"jobs":{"status":"GET /v1/jobs/{job_id} - Authenticated job status","cancel":"DELETE /v1/jobs/{job_id} - Authenticated job cancellation","progress_ws":"WS /v1/jobs/{job_id}/progress - Authenticated job progress stream"},"users":{"create":"POST /v1/users - Authenticated dev/operational user creation","whoami":"GET /v1/auth/whoami - Inspect current user, key, and credits","capability_gaps":"GET /v1/feedback/capability-gaps - List recent missing-capability reports","capability_gap_summary":"GET /v1/feedback/capability-gaps/summary - Summarize repeated unmet demand","capability_gap_export":"GET /v1/feedback/capability-gaps/export - Export raw reports as CSV","me":"GET /v1/users/me - Get current user","update_me":"PATCH /v1/users/me - Update current user profile","keys":"GET /v1/users/me/keys - List API keys","create_key":"POST /v1/users/me/keys - Create API key","revoke_key":"DELETE /v1/users/me/keys/{key_id} - Revoke key"},"billing":{"credits":"GET /v1/billing/credits - Check credit balance","usage":"GET /v1/billing/usage - Get usage summary","tier":"GET /v1/billing/tier - Get billing tier"},"health":{"health":"GET /health","ready":"GET /ready"},"dashboard":{"url":"/dashboard - Web dashboard for usage monitoring"}},"authentication":{"type":"API key","header":"Authorization: Bearer <api_key>","format":"pref_live_xxx, pref_test_xxx, or pref_agent_xxx","onboarding":"Humans should sign in on the website and create keys from onboarding. Agents should register via POST /v1/agents/register for an API key."},"streaming":{"websocket":{"url":"ws://localhost:{port}/v1/jobs/{{job_id}}/progress","format":{"type":"progress","task_id":"string","progress":"float (0.0-1.0)","message":"string","timestamp":"ISO 8601 datetime"}},"sse":{"url":"http://localhost:{port}/v1/jobs/{{job_id}}/stream","events":["progress","complete"]}}}