cyanheads-mcp-server

Search fleet tools and servers by natural-language description. Returns ranked matches with brief summaries and the server each tool belongs to. Use scope "servers" to find which server handles a workflow; use the default scope "tools" to find specific tools.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "pattern": "\\S",
      "description": "Natural language search query. Describe what you want to accomplish, a workflow, or a capability area. 1-500 raw characters; surrounding whitespace is trimmed. Must contain non-whitespace text."
    },
    "scope": {
      "default": "tools",
      "description": "What to search. \"tools\" returns individual tool matches; \"servers\" returns server-level matches.",
      "type": "string",
      "enum": [
        "tools",
        "servers"
      ]
    },
    "category": {
      "description": "Filter by catalog category. Omit to search all categories.",
      "type": "string",
      "enum": [
        "research",
        "government",
        "public-data",
        "utility"
      ]
    },
    "limit": {
      "default": 5,
      "description": "Maximum number of results to return (1-20). Default 5.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "offset": {
      "default": 0,
      "description": "Result offset. Use nextOffset with the same query, scope, category, and limit; pages use the current catalog.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "serversOffset": {
      "default": 0,
      "description": "Independent server roll-up offset (10 per page). Use nextServersOffset; must be zero in servers scope.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "offset": {
      "type": "number",
      "description": "Current ranked-result offset."
    },
    "nextOffset": {
      "description": "Next ranked-result offset, or null when exhausted.",
      "type": [
        "number",
        "null"
      ]
    },
    "serversOffset": {
      "description": "Current server roll-up offset; tools scope only.",
      "type": "number"
    },
    "nextServersOffset": {
      "description": "Next server roll-up offset, or null when exhausted; tools scope only.",
      "type": [
        "number",
        "null"
      ]
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Tool name (snake_case) or server name (kebab-case) depending on scope."
          },
          "server": {
            "type": "string",
            "description": "Server package name that owns this tool (e.g. \"arxiv-mcp-server\"). Same as name when scope is \"servers\"."
          },
          "brief": {
            "type": "string",
            "description": "One-line summary of what this tool or server does."
          },
          "category": {
            "type": "string",
            "enum": [
              "research",
              "government",
              "public-data",
              "utility"
            ],
            "description": "Catalog category for the owning server."
          },
          "score": {
            "type": "number",
            "description": "Cosine similarity between query and entry, in [0, 1]. Higher is better. Compare only within a single response."
          }
        },
        "required": [
          "name",
          "server",
          "brief",
          "category",
          "score"
        ],
        "additionalProperties": false,
        "description": "A single search result entry."
      },
      "description": "Ranked matches, best first."
    },
    "scope": {
      "type": "string",
      "enum": [
        "tools",
        "servers"
      ],
      "description": "Scope that was searched."
    },
    "servers": {
      "description": "Server roll-up from the full match set, independent of result offset/limit. Tools scope only. Ordered by topScore desc (name-tiebroken); 10 per page starting at serversOffset. Use nextServersOffset to continue and serversTotal for the full distinct count.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Server package name (e.g. \"cdc-health-mcp-server\")."
          },
          "brief": {
            "type": "string",
            "description": "One-line description of what the server does."
          },
          "category": {
            "type": "string",
            "enum": [
              "research",
              "government",
              "public-data",
              "utility"
            ],
            "description": "Catalog category."
          },
          "matchedTools": {
            "type": "number",
            "description": "Count of this server's tools in the full match set."
          },
          "topScore": {
            "type": "number",
            "description": "Best cosine similarity among this server's matched tools. Drives ordering. Distinct from the score a server gets under scope \"servers\"."
          }
        },
        "required": [
          "name",
          "brief",
          "category",
          "matchedTools",
          "topScore"
        ],
        "additionalProperties": false,
        "description": "A server roll-up entry."
      }
    },
    "serversTotal": {
      "description": "Total distinct servers in the full match set (before the cap of 10 is applied). Present only when servers is present.",
      "type": "number"
    },
    "effectiveQuery": {
      "type": "string",
      "description": "The query that was searched."
    },
    "totalCount": {
      "type": "number",
      "description": "Total relevant matches before the limit was applied."
    },
    "notice": {
      "description": "Guidance for zero matches or an exhausted result page. Absent on nonempty result pages.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_servers_offset`: A nonzero serversOffset is supplied in servers scope. `catalog_empty`: Catalog has not finished loading. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_servers_offset",
                "catalog_empty"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "offset",
        "nextOffset",
        "results",
        "scope",
        "effectiveQuery",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Return the description and install snippets for a named tool or server. For tools: the description, owning server, and connection metadata. For either kind: local (stdio, via npx) install snippets for every published server, plus remote (HTTP) connection snippets when a hosted endpoint exists — for every supported client, or one client via the client parameter.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Tool name (snake_case, e.g. \"earthquake_search\") or server name (kebab-case, e.g. \"earthquake-mcp-server\"). 1-64 characters. Exact names win; unique case-insensitive names resolve to canonical names. Use cyanheads_search_catalog to discover valid names."
    },
    "kind": {
      "description": "Whether name refers to a tool or server. Omit to auto-detect: names containing underscores are treated as tools; names containing hyphens are treated as servers.",
      "type": "string",
      "enum": [
        "tool",
        "server"
      ]
    },
    "client": {
      "description": "Return install snippets for this client only (both local and remote transports when available). Omit to return snippets for all supported clients.",
      "type": "string",
      "enum": [
        "claude-code",
        "codex",
        "cursor",
        "curl",
        "gemini",
        "streamable-http"
      ]
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "tool",
              "description": "Resolved as a tool entry."
            },
            "name": {
              "type": "string",
              "description": "Canonical resolved tool name."
            },
            "description": {
              "type": "string",
              "description": "Brief description of what the tool does."
            },
            "server": {
              "type": "string",
              "description": "Server package name that owns this tool."
            },
            "npm": {
              "type": "string",
              "description": "Owning server npm package for local installation."
            },
            "github": {
              "type": "string",
              "description": "Owning server GitHub repository URL."
            },
            "endpoint": {
              "description": "Owning server hosted HTTP endpoint, when available.",
              "type": "string"
            },
            "auth": {
              "type": "string",
              "description": "Owning server hosted authentication requirement."
            },
            "requiredEnvVars": {
              "description": "Environment variable names required for local installation.",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "installNotice": {
              "description": "Actionable guidance when the requested client has no compatible installation snippet.",
              "type": "string"
            },
            "installSnippets": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "client": {
                    "type": "string",
                    "enum": [
                      "claude-code",
                      "codex",
                      "cursor",
                      "curl",
                      "gemini",
                      "streamable-http"
                    ],
                    "description": "Target MCP client."
                  },
                  "transport": {
                    "type": "string",
                    "enum": [
                      "stdio",
                      "http"
                    ],
                    "description": "Local stdio or hosted HTTP transport."
                  },
                  "label": {
                    "type": "string",
                    "description": "Install method label."
                  },
                  "payload": {
                    "type": "string",
                    "description": "Install command or configuration."
                  }
                },
                "required": [
                  "client",
                  "transport",
                  "label",
                  "payload"
                ],
                "additionalProperties": false,
                "description": "An installation snippet for the owning server."
              },
              "description": "Owning server install snippets, filtered by client when supplied."
            }
          },
          "required": [
            "kind",
            "name",
            "description",
            "server",
            "npm",
            "github",
            "auth",
            "installSnippets"
          ],
          "additionalProperties": false,
          "description": "A resolved tool entry — its description and the server that owns it."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "server",
              "description": "Resolved as a server entry."
            },
            "name": {
              "type": "string",
              "description": "Canonical resolved server name."
            },
            "displayName": {
              "type": "string",
              "description": "Human-readable server label."
            },
            "description": {
              "type": "string",
              "description": "Brief description of what the server does."
            },
            "version": {
              "type": "string",
              "description": "Published version captured at fleet-generation time."
            },
            "npm": {
              "type": "string",
              "description": "npm package name (e.g. \"@cyanheads/arxiv-mcp-server\"). Drives the local stdio snippets."
            },
            "github": {
              "type": "string",
              "description": "GitHub repository URL."
            },
            "endpoint": {
              "description": "Streamable HTTP endpoint for the hosted deployment. Absent for local-only (stdio) servers.",
              "type": "string"
            },
            "auth": {
              "type": "string",
              "description": "Auth requirement for the hosted deployment (currently always \"none\")."
            },
            "requiredEnvVars": {
              "description": "Env var names the local (stdio) install requires (e.g. [\"MAILCHIMP_API_KEY\"]). Absent when none.",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "installNotice": {
              "description": "Actionable guidance when the requested client has no compatible installation snippet.",
              "type": "string"
            },
            "toolCount": {
              "type": "number",
              "description": "Number of tools exposed by this server."
            },
            "tools": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Tool name (snake_case, e.g. \"earthquake_search\")."
                  },
                  "description": {
                    "type": "string",
                    "description": "Brief description of what the tool does."
                  }
                },
                "required": [
                  "name",
                  "description"
                ],
                "additionalProperties": false,
                "description": "A single tool exposed by this server."
              },
              "description": "Every tool this server exposes, each with its name and a brief description — one describe call reveals the full surface without a second lookup."
            },
            "installSnippets": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "client": {
                    "type": "string",
                    "enum": [
                      "claude-code",
                      "codex",
                      "cursor",
                      "curl",
                      "gemini",
                      "streamable-http"
                    ],
                    "description": "MCP client this snippet targets."
                  },
                  "transport": {
                    "type": "string",
                    "enum": [
                      "stdio",
                      "http"
                    ],
                    "description": "Transport this snippet installs — stdio (local) or http (remote)."
                  },
                  "label": {
                    "type": "string",
                    "description": "Human-readable install method label."
                  },
                  "payload": {
                    "type": "string",
                    "description": "Install payload (JSON fragment or CLI command)."
                  }
                },
                "required": [
                  "client",
                  "transport",
                  "label",
                  "payload"
                ],
                "additionalProperties": false,
                "description": "A single install instruction entry."
              },
              "description": "Install instructions: local (stdio) snippets for every server, plus remote (HTTP) snippets when an endpoint exists. Filtered to one client when input.client is set."
            }
          },
          "required": [
            "kind",
            "name",
            "displayName",
            "description",
            "version",
            "npm",
            "github",
            "auth",
            "toolCount",
            "tools",
            "installSnippets"
          ],
          "additionalProperties": false,
          "description": "A resolved server entry — metadata, optional hosted endpoint, and per-client install snippets."
        }
      ],
      "description": "The resolved entry — either a tool detail or a server detail depending on the resolved kind."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: No tool or server with the given name exists in the catalog. `ambiguous_kind`: Name matches both a tool and a server (collision in catalog). `catalog_empty`: Catalog has not finished loading. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "ambiguous_kind",
                "catalog_empty"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "result"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}