---

Tools

Two tools, semantic ranking, hosted catalog. The catalog itself lives at caseyjhand.com/fleet.json — a single JSON file with baked embeddings, regenerated when servers are added or updated. This server polls it hourly and serves search out of an in-memory vector index.

cyanheads_search

Semantic search across the fleet. Embeds the query with Snowflake Arctic Embed M v1.5 (Matryoshka-truncated to 256 dimensions) and computes cosine similarity against the catalog's pre-computed document vectors.

• scope: "tools" (default) returns individual tool matches; scope: "servers" returns server-level matches
• category filter narrows to one of research, government, public-data, utility
• Configurable limit (1-20, default 5) and a server-side SIMILARITY_FLOOR threshold drop low-confidence hits
• Returns score (cosine similarity in [0, 1]) on every result for trust calibration
• totalMatched reports the count above the floor before the limit was applied

---

cyanheads_describe

Resolve a name to its install instructions. Accepts either a tool name (snake_case, e.g. earthquake_search) or a server name (kebab-case, e.g. earthquake-mcp-server) — auto-detected from the format, or pinned via the kind parameter.

• For tools: returns the description and the owning server name
• For servers: returns description, version, npm package, GitHub URL, the full tool list (each tool's name and description), and per-client install snippets — local (stdio, via npx) for every server, plus remote (Streamable HTTP) when a hosted endpoint exists
• Each snippet carries a transport (stdio or http); env vars a local install needs are surfaced and scaffolded into the JSON configs
• client filter narrows snippets to one of claude-code, codex, cursor, gemini, streamable-http, curl; omit to return every client
• Discriminated output on kind — callers branch on data, not string parsing

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling with typed error contracts and recovery hints
• Pluggable auth (none, jwt, oauth)
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

Fleet-specific:

• Hourly background catalog refresh with atomic swap on generatedAt change — no restart needed when the fleet updates
• L2-normalized 256-dim Matryoshka-truncated vectors keep memory under 100KB for a 40-server fleet
• Per-client install snippet generation at describe-time, not catalog-generation time — both local (stdio npx) and remote (Streamable HTTP) transports, kept in sync with the deployed endpoint
• Discriminated result.kind and typed installSnippets[].client / installSnippets[].transport enums — agents can branch reliably

What's in the fleet

40+ MCP servers spanning four categories. Each is open source and individually addressable — cyanheads_describe returns its direct connection URL alongside the install snippet.

Getting started

Public Hosted Instance

A public instance is available at https://cyanheads.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "cyanheads-mcp-server": {
      "type": "streamable-http",
      "url": "https://cyanheads.caseyjhand.com/mcp"
    }
  }
}

For Claude Code:

claude mcp add --transport http cyanheads https://cyanheads.caseyjhand.com/mcp

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "cyanheads-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/cyanheads-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "cyanheads-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/cyanheads-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "cyanheads-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cyanheads-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/cyanheads-mcp-server.git

2. Navigate into the directory:

cd cyanheads-mcp-server

3. Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Every variable has a sensible default — out of the box, the server points at the canonical cyanheads fleet.

To point at a different catalog, change CATALOG_URL to your own hosted JSON file. See docs/design.md for the producer-side script and schema.

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, runs MCP and packaging linters
  bun run test      # Runs the test suite
  

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage
• Register new tools in src/mcp-server/tools/definitions/index.ts

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.