agent-discover

MCP server registry and marketplace. Discover, install, activate, and manage MCP tools on demand. Acts as a dynamic proxy -- activated servers have their tools merged into the registry's own tool list, so agents can use them without restarting.

Search spans the official MCP registry, npm, and PyPI in one query, so popular servers that aren't in the official index (Microsoft @playwright/mcp, @modelcontextprotocol/server-*, mcp-server-fetch, mcp-server-git, …) all show up.

Built for AI coding agents (Claude Code, Codex CLI, Gemini CLI, Aider) but works equally well with any MCP client, REST consumer, or WebSocket listener.

Light Theme	Dark Theme

Why

Static MCP configs mean every server is always running, even when unused. Adding a new server requires editing config files and restarting. There is no way to browse what is available or install new tools at runtime.

Features

• Single-call tool discovery (find_tool) — hybrid BM25 + semantic ranking returns the top match with a confidence label, compact required_args, and 4 ranked alternatives. Auto-activates the owning child server so the agent can call the proxied tool immediately on the next turn. Replaces the multi-step search → list → activate dance with one round-trip.
• Batch discovery (find_tools) — pass an array of intents to discover N tools in a single round-trip for multi-step tasks.
• Indirect invocation (proxy_call) — call a discovered tool through agent-discover without exposing it to the host catalog. Keeps the host MCP surface at exactly 5 actions regardless of how many tools the registered child servers expose — critical for very large catalogs where flooding the host with thousands of schemas would blow the model's context budget.
• Pluggable embeddings (AGENT_DISCOVER_EMBEDDING_PROVIDER) — semantic search is opt-in via none (default, BM25 only) / local (Xenova/all-MiniLM-L6-v2 via @huggingface/transformers) / openai (text-embedding-3-small). Provider failures fall back to BM25 cleanly. Mirrors agent-knowledge's pattern so the same model can be reused.
• did_you_mean recovery — when a proxied tool call fails, the proxy attaches BM25-ranked similar-tool suggestions to the error response so the agent can correct in one extra turn instead of giving up.
• Local registry -- register MCP servers in a SQLite database with name, command, args, env, tags
• Federated marketplace search -- a single query hits the official MCP registry, npm, and PyPI in parallel, dedupes by <source>:<name>, and collapses version duplicates
• PyPI integration -- curated list of well-known Python MCP servers (mcp-server-fetch, mcp-server-git, mcp-server-time, mcp-server-postgres, mcp-server-sqlite, mcp-proxy, …) plus live metadata via the PyPI JSON API; Python entries install via uvx
• npm fallback -- two parallel npm searches (keywords:mcp and <query> mcp) catch packages that didn't tag themselves (e.g. Microsoft @playwright/mcp)
• Prereqs probe -- GET /api/prereqs reports which package managers (npx, uvx, docker, uv) are available on the host; the dashboard surfaces a banner when something needed for an install is missing
• Cross-process activation -- the active flag is the source of truth in SQLite; every fresh agent-discover process hydrates its in-memory proxy from the DB on startup, so tools activated in one process show up in others
• On-demand activation -- activate/deactivate servers at runtime; their tools appear and disappear dynamically with tools/list_changed notifications
• Tool proxying -- activated server tools are namespaced as serverName__toolName and merged into the tool list
• Multi-transport -- stdio, SSE, and streamable-http transports for connecting to child servers
• Secret management -- store API keys and tokens per server, automatically injected as env vars (stdio) or HTTP headers (SSE/streamable-http) on activation; CRLF-validated to prevent header injection
• Health checks -- connect/disconnect probes for inactive servers, tool-list checks for active ones, with error count tracking
• Per-tool metrics -- call counts, error counts, and average latency recorded automatically on every proxied tool call
• Full-text search -- FTS5 search across server names, descriptions, and tags + cross-server tool index for find_tool
• Pre-download -- fire-and-forget npm cache add (npx servers) or uv tool install (uvx servers) on registration, plus a dedicated /preinstall endpoint
• Real-time dashboard -- web UI at http://localhost:3424 with Servers and Browse tabs, dark/light theme, WebSocket updates
• 3 transport layers -- MCP (stdio), REST API (HTTP), WebSocket (real-time events)
• Declarative setup file -- set AGENT_DISCOVER_SETUP_FILE to a JSON file listing servers to ensure-registered on startup. Idempotent (skips existing). Supports auto_activate, env var secret refs ($VAR), and tags. Automatically also reads a .local.json variant (e.g. discover-setup.local.json) for machine-specific servers with secrets. New registry({ action: "sync" }) MCP action and POST /api/sync REST endpoint for on-demand re-read.
• Bench harness -- under bench/, comparing eager tool loading vs deferred discovery against real Claude Code and OpenCode hosts. Headline result at N=1000 against an adversarial natural-language verb pack: discover 100% accuracy + 27% lower per-turn token cost vs eager 80% accuracy. See bench/README.md.

Quick Start

Install from npm

npm install -g agent-discover

Or run directly with npx

npx agent-discover

Or clone from source

git clone https://github.com/keshrath/agent-discover.git
cd agent-discover
npm install
npm run build

Option 1: MCP server (for AI agents)

Add to your MCP client config (Claude Code, Cline, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "agent-discover": {
      "command": "npx",
      "args": ["agent-discover"]
    }
  }
}

The dashboard auto-starts at http://localhost:3424 on the first MCP connection.

Option 2: Standalone server (for REST/WebSocket clients)

node dist/server.js --port 3424

MCP Tools (1)

A single action-based tool handles every operation via the action parameter — this keeps the prompt-overhead cost minimal regardless of how many child servers are registered.

Activated servers expose their tools through agent-discover, namespaced as serverName__toolName. For example, activating a server named filesystem that exposes read_file makes it available as filesystem__read_file.

When find_tool is called with auto_activate: false (recommended for catalogs above ~1k tools), the proxy connection is opened silently and tools must be invoked via proxy_call instead of being added to the host's catalog. This keeps the host MCP surface area constant regardless of how many tools the registered child servers expose.

REST API (19 endpoints)

All endpoints return JSON. CORS enabled.

GET    /health                            Version, uptime
GET    /api/prereqs                       Probe host for npx/uvx/docker/uv availability
GET    /api/servers                       List servers (?query=, ?source=, ?installed=)
GET    /api/servers/:id                   Server details + tools
POST   /api/servers                       Register new server
PUT    /api/servers/:id                   Update server config (description, command, args, env, tags)
DELETE /api/servers/:id                   Unregister (deactivates first if active)
POST   /api/servers/:id/activate          Activate -- start server, discover tools, begin proxying
POST   /api/servers/:id/deactivate        Deactivate -- stop server, remove tools
POST   /api/servers/:id/preinstall        Pre-download package (npm cache add for npx, uv tool install for uvx)
GET    /api/servers/:id/secrets           List secrets (masked values)
PUT    /api/servers/:id/secrets/:key      Set a secret (upsert)
DELETE /api/servers/:id/secrets/:key      Delete a secret
POST   /api/servers/:id/health            Run health check (connect/disconnect probe)
GET    /api/servers/:id/metrics           Per-tool metrics for a server (call count, errors, latency)
GET    /api/metrics                       Metrics overview across all servers
GET    /api/browse                        Federated search: official registry + npm + PyPI (?query=, ?limit=, ?cursor=)
GET    /api/npm-check                     Check if an npm package exists (?package=)
GET    /api/status                        Active servers summary (names, tool counts, tool lists)

Dashboard

The web dashboard auto-starts at http://localhost:3424 and provides two views:

Servers tab -- all registered servers as cards showing health dots, error counts, active/inactive status, description, tags, tools list, and expandable Secrets/Metrics/Config sections. Action buttons for activate, deactivate, health check, and delete.

Browse tab -- federated search across the official MCP registry, npm, and PyPI. Each card shows the runtime tag (node, python, streamable-http, …), version, description, and an install button that picks the right command (npx, uvx, or remote URL) automatically. A prereq banner at the top of the tab warns when a required package manager (npx, uvx, docker) is missing on the host.

Real-time updates via WebSocket with 2-second database polling. Dark and light themes with persistent preference.

Testing

npm test              # 179 tests across 12 files
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run check         # Full CI: typecheck + lint + format + test
npm run test:e2e:ui   # Playwright dashboard smoke tests

Environment Variables

Core

Embeddings (semantic search for find_tool)

Embeddings are opt-in. The default is none, which means find_tool ranks by BM25 + verb synonyms only. Setting a provider enables hybrid BM25 + cosine retrieval, which closes the natural-language gap (e.g. "billing arrangement" → "subscription") that BM25 alone misses.

Local provider uses Xenova/all-MiniLM-L6-v2 (384 dims) via @huggingface/transformers. Install the optional peer dependency with npm install @huggingface/transformers if you want to use it. No network calls, no API key.

OpenAI provider uses text-embedding-3-small (1536 dims). Same model as agent-knowledge so the two servers can share an embedding key.

Host package manager prerequisites

agent-discover spawns child MCP servers via the host's installed package managers. Install whatever you intend to use; missing tools are reported by GET /api/prereqs and surfaced as a banner in the Browse tab.

Documentation

• User Manual -- comprehensive guide covering all tools, REST API, dashboard, and troubleshooting
• API Reference -- all MCP tools and REST endpoints
• Architecture -- source structure, design principles, database schema
• Dashboard -- web UI views and features
• Setup Guide -- installation, client setup (Claude Code, Cursor, Windsurf)
• Changelog

License

MIT -- see LICENSE