{"openapi":"3.1.0","info":{"title":"MCP Vetted API","version":"0.1.0","description":"An AI-run search engine and installer for MCP servers. Every version is checked automatically and given a trust tier. Built for agents; people are welcome. The same operations are available as MCP tools at https://mcpvetted.com/api/mcp."},"servers":[{"url":"https://mcpvetted.com/api/v1"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional. Raises rate limits."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"}}}}}}},"paths":{"/search":{"get":{"operationId":"search_tools","summary":"Search tools","description":"Searches the vetted index of MCP servers by keyword or by the job a tool does. Returns each result's trust tier, observed access, check results and trust page URL.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Keywords or a plain description of the job, e.g. 'schedule LinkedIn posts'."},"description":"Keywords or a plain description of the job, e.g. 'schedule LinkedIn posts'."},{"name":"kind","in":"query","required":false,"schema":{"description":"Limit to one tool type. Only mcp_server is indexed today.","type":"string","enum":["mcp_server","automation","extension","app"]},"description":"Limit to one tool type. Only mcp_server is indexed today."},{"name":"min_tier","in":"query","required":false,"schema":{"description":"Lowest tier to include: indexed < scanned < verified < proven.","type":"string","enum":["indexed","scanned","verified","proven"]},"description":"Lowest tier to include: indexed < scanned < verified < proven."},{"name":"limit","in":"query","required":true,"schema":{"default":5,"type":"integer","minimum":1,"maximum":25}},{"name":"cursor","in":"query","required":false,"schema":{"description":"Opaque cursor from a previous response's next_cursor.","type":"string"},"description":"Opaque cursor from a previous response's next_cursor."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"tier":{"type":"string"},"tierMeaning":{"type":"string"},"latestVersion":{"type":"string"},"revoked":{"type":"boolean"},"access":{"nullable":true,"type":"object","properties":{"networkHosts":{"type":"array","items":{"type":"string"}},"filePaths":{"type":"array","items":{"type":"string"}},"accounts":{"type":"array","items":{"type":"string"}},"observedBy":{"type":"string"}},"required":["networkHosts","filePaths","accounts","observedBy"],"additionalProperties":false},"checks":{"type":"array","items":{"type":"object","properties":{"check":{"type":"string"},"verdict":{"type":"string"},"ranAt":{"type":"string"}},"required":["check","verdict","ranAt"],"additionalProperties":false}},"rulesVersion":{"nullable":true,"type":"string"},"installs":{"type":"number"},"trustPageUrl":{"type":"string"},"markdownUrl":{"type":"string"},"demo":{"type":"boolean"},"why":{"type":"array","items":{"type":"string"}}},"required":["slug","name","title","kind","summary","tier","tierMeaning","latestVersion","revoked","access","checks","rulesVersion","installs","trustPageUrl","markdownUrl","demo","why"],"additionalProperties":false}},"total":{"type":"number"},"next_cursor":{"nullable":true,"type":"string"}},"required":["results","total","next_cursor"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/{slug}":{"get":{"operationId":"get_tool","summary":"Get tool details","description":"Returns one indexed tool by slug, registry name or server URL: versions, tier history, observed access and supported apps.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"tier":{"type":"string"},"tierMeaning":{"type":"string"},"latestVersion":{"type":"string"},"revoked":{"type":"boolean"},"access":{"nullable":true,"type":"object","properties":{"networkHosts":{"type":"array","items":{"type":"string"}},"filePaths":{"type":"array","items":{"type":"string"}},"accounts":{"type":"array","items":{"type":"string"}},"observedBy":{"type":"string"}},"required":["networkHosts","filePaths","accounts","observedBy"],"additionalProperties":false},"checks":{"type":"array","items":{"type":"object","properties":{"check":{"type":"string"},"verdict":{"type":"string"},"ranAt":{"type":"string"}},"required":["check","verdict","ranAt"],"additionalProperties":false}},"rulesVersion":{"nullable":true,"type":"string"},"installs":{"type":"number"},"trustPageUrl":{"type":"string"},"markdownUrl":{"type":"string"},"demo":{"type":"boolean"},"publisher":{"type":"object","properties":{"name":{"type":"string"},"claimed":{"type":"boolean"},"verifiedDomain":{"nullable":true,"type":"string"}},"required":["name","claimed","verifiedDomain"],"additionalProperties":false},"websiteUrl":{"nullable":true,"type":"string"},"repositoryUrl":{"nullable":true,"type":"string"},"versions":{"type":"array","items":{"type":"object","properties":{"version":{"type":"string"},"tier":{"type":"string"},"releasedAt":{"type":"string"},"revoked":{"type":"boolean"},"revokedReason":{"nullable":true,"type":"string"}},"required":["version","tier","releasedAt","revoked","revokedReason"],"additionalProperties":false}},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name","description"],"additionalProperties":false}},"outcomes":{"type":"object","properties":{"worked":{"type":"number"},"failed":{"type":"number"}},"required":["worked","failed"],"additionalProperties":false},"sources":{"type":"array","items":{"type":"string"}}},"required":["slug","name","title","kind","summary","tier","tierMeaning","latestVersion","revoked","access","checks","rulesVersion","installs","trustPageUrl","markdownUrl","demo","publisher","websiteUrl","repositoryUrl","versions","tools","outcomes","sources"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/{slug}/trust":{"get":{"operationId":"get_trust_report","summary":"Get trust report","description":"Returns each check's verdict and findings for one version of a tool, with the rules version and when each check ran.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","required":false,"schema":{"description":"Defaults to the latest version.","type":"string"},"description":"Defaults to the latest version."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"version":{"type":"string"},"tier":{"type":"string"},"tierMeaning":{"type":"string"},"revoked":{"nullable":true,"type":"object","properties":{"at":{"type":"string"},"reason":{"type":"string"}},"required":["at","reason"],"additionalProperties":false},"checks":{"type":"array","items":{"type":"object","properties":{"check":{"type":"string"},"verdict":{"type":"string"},"rulesVersion":{"type":"string"},"ranAt":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"severity":{"type":"string"},"message":{"type":"string"},"location":{"type":"string"}},"required":["rule","severity","message"],"additionalProperties":false}}},"required":["check","verdict","rulesVersion","ranAt","findings"],"additionalProperties":false}},"trustPageUrl":{"type":"string"}},"required":["slug","version","tier","tierMeaning","revoked","checks","trustPageUrl"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/{slug}/install":{"get":{"operationId":"get_install_config","summary":"Get install config","description":"Returns the exact install link, command or config block one app accepts for a tool, pinned to the vetted version, plus the access to show the user before installing. Records an install id for outcome reports.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"client","in":"query","required":true,"schema":{"type":"string","enum":["vscode","cursor","claude_code","claude_desktop","claude_ai"],"description":"The app to install into."},"description":"The app to install into."},{"name":"version","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"install_id":{"nullable":true,"type":"string"},"client":{"type":"string"},"label":{"type":"string"},"supported":{"type":"boolean"},"link":{"nullable":true,"type":"string"},"command":{"nullable":true,"type":"string"},"config":{"nullable":true,"type":"object","additionalProperties":{}},"steps":{"type":"array","items":{"type":"string"}},"pinned":{"type":"object","properties":{"version":{"type":"string"},"contentHash":{"type":"string"}},"required":["version","contentHash"],"additionalProperties":false},"tier":{"type":"string"},"access":{"nullable":true,"type":"object","properties":{"networkHosts":{"type":"array","items":{"type":"string"}},"filePaths":{"type":"array","items":{"type":"string"}},"accounts":{"type":"array","items":{"type":"string"}}},"required":["networkHosts","filePaths","accounts"],"additionalProperties":false},"env":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"secret":{"type":"boolean"}},"required":["name"],"additionalProperties":false}},"note":{"nullable":true,"type":"string"}},"required":["install_id","client","label","supported","link","command","config","steps","pinned","tier","access","env","note"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/{slug}/policy":{"get":{"operationId":"check_policy","summary":"Check against a policy","description":"Checks one tool against a minimum tier and a list of blocked access types, and returns allow or deny with the reasons.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"min_tier","in":"query","required":true,"schema":{"default":"scanned","type":"string","enum":["indexed","scanned","verified","proven"]}},{"name":"blocked_access","in":"query","required":true,"schema":{"default":[],"type":"array","items":{"type":"string","enum":["network","files","accounts"]}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"allowed":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"tier":{"type":"string"}},"required":["slug","allowed","reasons","tier"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compare":{"get":{"operationId":"compare_tools","summary":"Compare tools","description":"Compares 2 to 5 tools side by side on tier, observed access, agent-reported outcomes and latest release.","parameters":[{"name":"slugs","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated slugs, 2 to 5."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"tier":{"type":"string"},"latestVersion":{"type":"string"},"released":{"type":"string"},"networkHosts":{"type":"number"},"fileAccess":{"type":"boolean"},"accounts":{"type":"array","items":{"type":"string"}},"outcomes":{"type":"object","properties":{"worked":{"type":"number"},"failed":{"type":"number"}},"required":["worked","failed"],"additionalProperties":false},"installs":{"type":"number"}},"required":["slug","title","tier","latestVersion","released","networkHosts","fileAccess","accounts","outcomes","installs"],"additionalProperties":false}}},"required":["tools"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/revocations":{"get":{"operationId":"list_revocations","summary":"List revocations","description":"Lists tool versions revoked after failing a check, newest first, optionally since a date or for specific tools.","parameters":[{"name":"since","in":"query","required":false,"schema":{"description":"ISO 8601 date-time.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"description":"ISO 8601 date-time."},{"name":"slugs","in":"query","required":false,"schema":{"maxItems":50,"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"revocations":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"version":{"type":"string"},"reason":{"type":"string"},"revokedAt":{"type":"string"},"trustPageUrl":{"type":"string"}},"required":["slug","version","reason","revokedAt","trustPageUrl"],"additionalProperties":false}}},"required":["revocations"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/submit":{"post":{"operationId":"submit_url","summary":"Submit a tool by URL","description":"Adds a tool to the index from an address: a remote MCP server URL, a domain, a GitHub repo, or an npm or PyPI package. Reads the server's self-description without calling its tools, then runs the standard checks.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":3,"maxLength":500,"description":"e.g. example.com/mcp, github.com/owner/repo, or @scope/package."}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"slug":{"nullable":true,"type":"string"},"tier":{"nullable":true,"type":"string"},"trustPageUrl":{"nullable":true,"type":"string"},"needsAuth":{"type":"boolean"},"steps":{"type":"array","items":{"type":"object","properties":{"step":{"type":"string"},"ok":{"type":"boolean"},"detail":{"type":"string"}},"required":["step","ok","detail"],"additionalProperties":false}},"error":{"nullable":true,"type":"string"}},"required":["ok","slug","tier","trustPageUrl","needsAuth","steps","error"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/outcomes":{"post":{"operationId":"report_outcome","summary":"Report install outcome","description":"Records whether a tool did its job after an install made with get_install_config. Reports from distinct agents feed the Proven tier.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"install_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The install_id returned by get_install_config."},"worked":{"type":"boolean"},"note":{"type":"string","maxLength":500}},"required":["install_id","worked"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"recorded":{"type":"boolean"}},"required":["recorded"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}