Guide MCP Navigator

Intelligent discovery and evaluation agent for finding, comparing, and integrating MCP servers across registries and community repositories.

When to Use This Agent

Choose this agent when you need to:

• Find MCP servers that expose specific tools or capabilities for your workflow
• Compare multiple registry listings to identify the best-maintained server for a use case
• Generate production-ready MCP client configuration files from discovered servers
• Evaluate server trustworthiness through metadata analysis and community signals

Consider alternatives when:

• You need to build a new MCP server from scratch (use MCP Server Strategist)
• Your concern is protocol-level specification compliance (use Specialist MCP Ally)

Quick Start

Configuration

Copy
name: guide-mcp-navigator
type: agent
category: mcp-dev-team

Example Invocation

Copy
claude agent:invoke guide-mcp-navigator "Find MCP servers for PostgreSQL database access with read-only tool annotations"

Example Output

Discovery Results (3 servers found)
====================================

1. postgresql-mcp (mcp.so)
   Transport: stdio, Streamable HTTP
   Tools: 12 (query, schema-inspect, explain-plan, ...)
   Annotations: read-only on all query tools
   Stars: 2,340 | Last updated: 2 days ago
   Trust Score: 94/100

2. db-connector-mcp (mcpmarket.com)
   Transport: stdio only
   Tools: 8 (query, list-tables, describe-column, ...)
   Annotations: partial (4/8 tools annotated)
   Stars: 890 | Last updated: 3 weeks ago
   Trust Score: 76/100

3. sql-bridge-mcp (GitHub community)
   Transport: Streamable HTTP
   Tools: 5 (execute-sql, get-schema, ...)
   Annotations: none
   Stars: 210 | Last updated: 4 months ago
   Trust Score: 52/100

Recommendation: postgresql-mcp - best coverage, active maintenance, full annotations

Core Concepts

Registry Landscape Overview

Aspect	Details
Primary Registries	mcp.so, mcpmarket.com, Speakeasy MCP Hub
Enterprise Registries	Azure API Center, Windows MCP Registry
Package Indexes	npm (@modelcontextprotocol/), PyPI (mcp-server-)
Discovery Signals	Stars, forks, download count, last commit date
Metadata Standard	mcp.json manifest with capabilities declaration
Trust Factors	Verified publisher, tool annotations, security audit status

Server Discovery Architecture

┌─────────────┐     ┌─────────────┐
│  Search      │────▶│  Registry    │
│  Query       │     │  Aggregator  │
└─────────────┘     └─────────────┘
        │                   │
        ▼                   ▼
┌─────────────┐     ┌─────────────┐
│  Capability  │────▶│  Ranked      │
│  Matcher     │     │  Results     │
└─────────────┘     └─────────────┘

Configuration

Parameter	Type	Default	Description
registries	string[]	["mcp.so","mcpmarket"]	Registries to search in priority order
minTrustScore	number	60	Minimum trust score threshold for results
transportFilter	enum	"any"	Filter by transport: stdio, streamable-http, any
requireAnnotations	boolean	false	Only return servers with complete tool annotations
maxResults	number	10	Maximum number of servers to return per query

Best Practices

1. Cross-Reference Multiple Registries Never rely on a single registry for server discovery. The same server may appear across mcp.so, npm, and GitHub with varying metadata completeness. Cross-referencing reveals discrepancies and helps identify the canonical source.

2. Prioritize Tool Annotation Completeness Servers that provide thorough tool annotations (read-only, destructive, idempotent) integrate more safely with AI agents. Annotations enable clients to enforce safety policies without custom logic per server.

3. Verify Transport Compatibility Before Integration Confirm the server supports your required transport layer before generating configuration. A server listed as supporting Streamable HTTP may only have implemented SSE fallback, which limits batching and bidirectional communication.

4. Check Maintenance Cadence Over Star Count A server with fewer stars but weekly commits is often more reliable than a popular but unmaintained project. Examine issue response times, release frequency, and dependency update patterns.

5. Cache Discovery Results Appropriately Registry APIs have rate limits. Implement local caching with a reasonable TTL (15-30 minutes) to avoid hitting limits during iterative searches while still receiving fresh results.

Common Issues

1. Registry API returns stale or missing capability metadata Some registries cache server metadata aggressively and may not reflect recent updates. Query the server's GitHub repository directly to fetch the latest mcp.json manifest and compare it against the registry listing.

2. Generated configuration fails to authenticate The server requires environment variables that are not documented in registry metadata. Check the server's README and issue tracker for authentication setup guides. Common missing variables include API keys, OAuth client IDs, and base URLs.

3. Search returns too many irrelevant results Broad keyword searches match against descriptions and tags loosely. Use capability-specific filters (transport type, tool count, annotation presence) to narrow results, and combine keyword search with the requireAnnotations flag for precision.