{"openapi":"3.1.0","info":{"title":"Agent Services Index","description":"Discoverability engine for agent-friendly MCP services and skills.","version":"0.2.0"},"paths":{"/.well-known/mcp.json":{"get":{"summary":"Well Known","operationId":"well_known","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WellKnownDoc"}}}}}}},"/search":{"post":{"summary":"Search","operationId":"search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/services":{"post":{"summary":"Register Service","operationId":"register_service","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/services/{service_id}":{"patch":{"summary":"Update Service","operationId":"update_service","parameters":[{"name":"service_id","in":"path","required":true,"schema":{"type":"string","title":"Service Id"}},{"name":"X-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/McpServerResult"},{"$ref":"#/components/schemas/AgentSkillResult"}],"discriminator":{"propertyName":"service_type","mapping":{"mcp_server":"#/components/schemas/McpServerResult","agent_skill":"#/components/schemas/AgentSkillResult"}},"title":"Response Update Service"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Deregister Service","operationId":"deregister_service","parameters":[{"name":"service_id","in":"path","required":true,"schema":{"type":"string","title":"Service Id"}},{"name":"X-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/report":{"post":{"summary":"Report Service","operationId":"report_service","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentSkillResult":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"service_type":{"type":"string","const":"agent_skill","title":"Service Type","default":"agent_skill"},"instructions":{"type":"string","title":"Instructions"},"setup_requirements":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Setup Requirements"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","default":[]}},"type":"object","required":["id","name","description","instructions"],"title":"AgentSkillResult"},"DeleteResponse":{"properties":{"id":{"type":"string","title":"Id"},"deleted":{"type":"boolean","title":"Deleted"}},"type":"object","required":["id","deleted"],"title":"DeleteResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"McpServerResult":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"service_type":{"type":"string","const":"mcp_server","title":"Service Type","default":"mcp_server"},"mcp_doc_url":{"type":"string","title":"Mcp Doc Url"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","default":[]}},"type":"object","required":["id","name","description","mcp_doc_url"],"title":"McpServerResult"},"RegisterRequest":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"Name"},"description":{"type":"string","maxLength":2000,"minLength":1,"title":"Description"},"service_type":{"type":"string","enum":["mcp_server","agent_skill"],"title":"Service Type"},"mcp_doc_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Mcp Doc Url"},"instructions":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Instructions"},"setup_requirements":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Setup Requirements"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"owner_contact":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Owner Contact"}},"type":"object","required":["name","description","service_type"],"title":"RegisterRequest"},"RegisterResponse":{"properties":{"id":{"type":"string","title":"Id"},"api_key":{"type":"string","title":"Api Key"},"note":{"type":"string","title":"Note","default":"Store this api_key now — it will not be shown again. Use it in the X-API-Key header to update or deregister this service."}},"type":"object","required":["id","api_key"],"title":"RegisterResponse"},"ReportRequest":{"properties":{"service_id":{"type":"string","title":"Service Id"},"issue":{"type":"string","enum":["unreachable","invalid_response","other"],"title":"Issue"},"details":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Details"}},"type":"object","required":["service_id","issue"],"title":"ReportRequest"},"ReportResponse":{"properties":{"service_id":{"type":"string","title":"Service Id"},"last_check_status":{"type":"string","enum":["ok","unreachable","invalid"],"title":"Last Check Status"},"substantiated":{"type":"boolean","title":"Substantiated"}},"type":"object","required":["service_id","last_check_status","substantiated"],"title":"ReportResponse"},"SearchRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":1,"title":"Query"},"limit":{"type":"integer","maximum":25.0,"minimum":1.0,"title":"Limit","default":10},"offset":{"type":"integer","minimum":0.0,"title":"Offset","default":0}},"type":"object","required":["query"],"title":"SearchRequest"},"SearchResponse":{"properties":{"results":{"items":{"oneOf":[{"$ref":"#/components/schemas/McpServerResult"},{"$ref":"#/components/schemas/AgentSkillResult"}],"discriminator":{"propertyName":"service_type","mapping":{"agent_skill":"#/components/schemas/AgentSkillResult","mcp_server":"#/components/schemas/McpServerResult"}}},"type":"array","title":"Results"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"total":{"type":"integer","title":"Total"},"instructions":{"type":"string","title":"Instructions","default":"Results include two types: MCP servers (service_type='mcp_server') with an mcp_doc_url you can fetch to connect, and agent skills (service_type='agent_skill') with instructions to follow and setup_requirements to satisfy. For MCP servers, GET the mcp_doc_url and connect via MCP. For skills, read the instructions, install any required packages or set required environment variables listed in setup_requirements, then follow the instructions. If an MCP server's mcp_doc_url is unreachable or returns invalid content, report it via POST /report with the service id. This keeps the index healthy for all agents."}},"type":"object","required":["results","limit","offset","total"],"title":"SearchResponse"},"UpdateRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":120,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Description"},"mcp_doc_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Mcp Doc Url"},"instructions":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Instructions"},"setup_requirements":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Setup Requirements"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"owner_contact":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Owner Contact"}},"type":"object","title":"UpdateRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WellKnownDoc":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"mcp_endpoint":{"type":"string","title":"Mcp Endpoint"},"openapi_url":{"type":"string","title":"Openapi Url"},"instructions":{"type":"string","title":"Instructions"},"tools":{"items":{"$ref":"#/components/schemas/WellKnownTool"},"type":"array","title":"Tools"}},"type":"object","required":["name","description","mcp_endpoint","openapi_url","instructions","tools"],"title":"WellKnownDoc"},"WellKnownTool":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["name","description"],"title":"WellKnownTool"}}}}