{ "openapi": "3.1.0", "info": { "title": "Toolweather API", "version": "1.0.0", "description": "Is this MCP server/tool safe to call right now? Live health verdicts for ~2,000 public MCP servers from the official registry, checked every 15 minutes, plus working alternatives. Free tier: 1,000 calls/day per key; email toolweather@mail.grokbot.com for a key. Change alerts: watch up to 3 servers per free key and receive signed HTTPS webhooks.", "contact": { "email": "toolweather@mail.grokbot.com", "url": "https://toolweather.pages.dev" }, "license": { "name": "MIT", "identifier": "MIT" } }, "servers": [ { "url": "https://toolweather.toolweather.workers.dev" } ], "externalDocs": { "url": "https://github.com/toolweather/toolweather" }, "security": [ { "apiKeyHeader": [] }, { "bearer": [] } ], "components": { "securitySchemes": { "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "Verdict": { "type": "object", "properties": { "server": { "type": "string" }, "url": { "type": "string" }, "transport": { "type": "string" }, "tool": { "type": [ "string", "null" ] }, "verdict": { "type": "string", "enum": [ "safe", "caution", "unsafe", "unknown" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "ok", "auth_required", "failed" ] }, "http_status": { "type": [ "integer", "null" ] }, "latency_ms": { "type": [ "number", "null" ] }, "protocol_version": { "type": [ "string", "null" ] }, "spec_readiness": { "type": "object" }, "auth": { "type": [ "object", "null" ] }, "tool_count": { "type": [ "integer", "null" ] }, "last_tool_change": { "type": [ "object", "null" ] }, "last_checked": { "type": "string", "format": "date-time" }, "other_endpoints": { "type": "array", "items": { "type": "object" } } }, "required": [ "verdict", "reasons" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "Watch": { "type": "object", "properties": { "id": { "type": "string" }, "server": { "type": "string" }, "webhook_url": { "type": "string", "format": "uri" }, "active": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "created": { "type": "string", "format": "date-time" }, "last_known": { "type": "object" }, "consecutive_failures": { "type": "integer" }, "last_delivery": { "type": [ "string", "null" ] } } }, "WebhookEvent": { "type": "object", "description": "POSTed to webhook_url. Verify X-Toolweather-Signature: t=,v1=. Headers also include X-Toolweather-Event and X-Toolweather-Delivery. Respond 2xx within 10 s; failures retry after 1, 5, 30, 120 and 360 minutes; a watch is disabled after 3 failed deliveries.", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "verdict_changed", "auth_required", "breaking_tool_change" ] }, "watch_id": { "type": "string" }, "created": { "type": "string" }, "server": { "type": "string" }, "url": { "type": "string" }, "verdict": { "type": "string" }, "status": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "previous": { "type": "object" }, "changes": { "type": "array", "items": { "type": "object" } }, "last_checked": { "type": "string" } } } } }, "paths": { "/v1/is_safe_to_call": { "get": { "operationId": "isSafeToCall", "summary": "Check whether an MCP server (and optionally a tool) is safe to call now", "parameters": [ { "name": "server", "in": "query", "required": true, "description": "Registry name (e.g. io.github.owner/name) or server URL", "schema": { "type": "string" } }, { "name": "tool", "in": "query", "required": false, "description": "Tool name to check against the current tool list", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verdict" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Free daily limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/suggest_alternatives": { "get": { "operationId": "suggestAlternatives", "summary": "Find working MCP servers with similar tools", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Server name/URL, or capability text like 'send email'", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "basis": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "object", "properties": { "server": { "type": "string" }, "url": { "type": "string" }, "verdict": { "type": "string" }, "latency_ms": { "type": [ "number", "null" ] }, "relevance": { "type": "number" }, "matching_tools": { "type": "array", "items": { "type": "string" } }, "last_checked": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Free daily limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/health": { "get": { "operationId": "health", "summary": "Service health and last data ingest time", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "last_ingest": { "type": [ "string", "null" ] } } } } } } } } }, "/badge/{name}.svg": { "get": { "operationId": "badge", "summary": "SVG status badge for a server", "security": [], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SVG badge", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } } } }, "/v1/watches": { "post": { "operationId": "watch_server", "summary": "Watch a server; get an HTTPS webhook on verdict change, new auth requirement, or breaking tool change", "security": [ { "apiKeyHeader": [] }, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "server", "webhook_url" ], "properties": { "server": { "type": "string", "description": "registry name or URL" }, "webhook_url": { "type": "string", "description": "public https URL (private/loopback addresses rejected)" } } } } } }, "responses": { "201": { "description": "Created. Includes the per-watch `secret` (shown once).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Watch" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] } } } }, "400": { "description": "Invalid input or webhook_url", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Free-tier limit (3 watches per key) reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Server not indexed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "callbacks": { "change": { "{$request.body#/webhook_url}": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged" } } } } } } }, "get": { "operationId": "list_watches", "summary": "List this key's watches", "security": [ { "apiKeyHeader": [] }, { "bearer": [] } ], "responses": { "200": { "description": "Watches", "content": { "application/json": { "schema": { "type": "object", "properties": { "watches": { "type": "array", "items": { "$ref": "#/components/schemas/Watch" } }, "free_tier": { "type": "object" } } } } } } } } }, "/v1/watches/{id}": { "delete": { "operationId": "unwatch_server", "summary": "Delete a watch", "security": [ { "apiKeyHeader": [] }, { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }