{"name":"preference MCP API","version":"1.0.0","description":"REST API wrapper for MCP tools 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","servers":"GET /v1/servers - List MCP servers with health status","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 MCP canary summary"},"gateway":{"route":"POST /mcp-gateway/{server_name} - Route to specific server (JSON-RPC 2.0)"},"jobs":{"status":"GET /v1/jobs/{job_id}","cancel":"DELETE /v1/jobs/{job_id}","progress_ws":"WS /v1/jobs/{job_id}/progress"},"users":{"create":"POST /v1/users - Create user (dev only)","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"]}}}