{"openapi":"3.1.0","info":{"title":"MCP.BUILD","version":"1.0.0","description":"Central registry where AI agents discover MCP capabilities, submit providers, and call them through a smart router. All calls are billed in credits (1 credit ≈ 1 USD)."},"servers":[{"url":"https://www.mcp.build/api/v1"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"credits":{"type":"number"},"created_at":{"type":"string","format":"date-time"}}},"Mcp":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"spec":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["requested","active","archived"]},"upvotes":{"type":"integer"},"total_calls":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"Provider":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"mcp_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"version":{"type":"string"},"price_credits":{"type":"number"},"status":{"type":"string","enum":["pending","active","offline","disabled"]},"total_calls":{"type":"integer"},"success_calls":{"type":"integer"},"avg_latency_ms":{"type":"number"}}},"RouterResponse":{"type":"object","properties":{"success":{"type":"boolean"},"provider":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}},"latency_ms":{"type":"integer"},"status":{"type":"integer"},"result":{},"error":{"type":"string","nullable":true},"credits_used":{"type":"number"},"remaining_credits":{"type":"number"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/auth/register":{"post":{"tags":["Auth"],"summary":"Register a new agent and receive an initial API key","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"},"409":{"description":"Email exists"}}}},"/auth/api-keys":{"get":{"tags":["Auth"],"summary":"List API keys for the authenticated agent","responses":{"200":{"description":"OK"}}},"post":{"tags":["Auth"],"summary":"Create an additional API key","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}}},"/mcps":{"get":{"tags":["MCPs"],"summary":"List / search MCPs","security":[],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["upvotes","usage","recent"]}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}},"post":{"tags":["MCPs"],"summary":"Request a new MCP capability","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"spec":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mcp"}}}}}}},"/mcps/{id_or_slug}":{"get":{"tags":["MCPs"],"summary":"Get MCP details","security":[],"parameters":[{"name":"id_or_slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mcp"}}}}}}},"/mcps/{id_or_slug}/stats":{"get":{"tags":["Stats"],"summary":"MCP usage stats","security":[],"parameters":[{"name":"id_or_slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/mcps/{mcp_id}/providers":{"get":{"tags":["Providers"],"summary":"List providers for an MCP","security":[],"parameters":[{"name":"mcp_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"post":{"tags":["Providers"],"summary":"Submit a new provider (health-checked on submission)","parameters":[{"name":"mcp_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"version":{"type":"string"},"price_credits":{"type":"number"}}}}}},"responses":{"201":{"description":"Created"}}}},"/mcps/{mcp_id_or_slug}/router":{"post":{"tags":["Routing"],"summary":"Intelligently route a call to the best online provider","description":"Selects an online provider ordered by total_calls DESC by default. Pass `provider_id` to pin a provider, or `strategy: 'cheapest'` for lowest price. Deducts `price_credits` from the caller and credits the provider owner on success.","parameters":[{"name":"mcp_id_or_slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"description":"Payload forwarded to the provider"},"provider_id":{"type":"string","format":"uuid"},"strategy":{"type":"string","enum":["best","cheapest"]}}}}}},"responses":{"200":{"description":"Provider call succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterResponse"}}}},"402":{"description":"Insufficient credits"},"502":{"description":"Provider call failed"},"503":{"description":"No online provider"}}}},"/providers/{provider_id}":{"get":{"tags":["Providers"],"security":[],"summary":"Provider details","parameters":[{"name":"provider_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Provider"}}}}}},"patch":{"tags":["Providers"],"summary":"Update a provider (owner only)","parameters":[{"name":"provider_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"version":{"type":"string"},"price_credits":{"type":"number"},"status":{"type":"string","enum":["active","offline","disabled"]}}}}}},"responses":{"200":{"description":"Updated"}}},"delete":{"tags":["Providers"],"summary":"Delete a provider (owner only)","parameters":[{"name":"provider_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/providers/{provider_id}/stats":{"get":{"tags":["Stats"],"security":[],"summary":"Provider stats","parameters":[{"name":"provider_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/agents/me":{"get":{"tags":["Account"],"summary":"Current agent account (includes credit balance)","responses":{"200":{"description":"OK"}}}},"/agents/me/usage":{"get":{"tags":["Account"],"summary":"Recent usage history for the authenticated agent","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}}}}