MCP Registry Navigator Agent

Automated registry operations agent for publishing, validating, and maintaining MCP server listings across the ecosystem.

When to Use This Agent

Choose this agent when you need to:

• Publish a new MCP server to one or more registries with validated metadata
• Audit existing registry listings for completeness and accuracy against the live server
• Bulk-update server metadata across multiple registries after a version release
• Analyze registry-level trends such as capability adoption rates or transport distribution

Consider alternatives when:

• You are searching for servers to consume rather than publish (use Guide MCP Navigator)
• You need to architect a new server implementation (use MCP Server Strategist)

Quick Start

Configuration

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

Example Invocation

Copy
claude agent:invoke mcp-registry-navigator-agent "Validate and publish my-analytics-mcp to mcp.so with full metadata"

Example Output

Registry Publication Report
============================
Server: my-analytics-mcp v2.1.0
Target: mcp.so

Metadata Validation:
  [PASS] mcp.json schema conforms to registry spec
  [PASS] All 7 tools have description and inputSchema
  [PASS] Tool annotations present (3 read-only, 2 idempotent, 2 destructive)
  [WARN] No completions capability declared
  [PASS] Transport: streamable-http, stdio
  [PASS] License: MIT

Publication Status: SUBMITTED
Review Queue Position: #12
Estimated approval: 24-48 hours

Core Concepts

Registry Operations Overview

Aspect	Details
Supported Registries	mcp.so, mcpmarket.com, Speakeasy Hub, npm, PyPI
Metadata Format	mcp.json with JSON Schema validation
Publication Flow	Validate locally, submit to registry, await review
Update Strategy	Semantic versioning triggers metadata sync
Listing Quality	Scored on annotation coverage, docs, and examples
Deprecation	Formal deprecation notice with migration pointer

Publication Pipeline Architecture

┌─────────────┐     ┌─────────────┐
│  mcp.json    │────▶│  Schema      │
│  Manifest    │     │  Validator   │
└─────────────┘     └─────────────┘
        │                   │
        ▼                   ▼
┌─────────────┐     ┌─────────────┐
│  Registry    │────▶│  Review      │
│  Submitter   │     │  Queue       │
└─────────────┘     └─────────────┘

Configuration

Parameter	Type	Default	Description
targetRegistries	string[]	["mcp.so"]	Registries to publish to or validate against
validateBeforePublish	boolean	true	Run full metadata validation before submission
autoSyncVersions	boolean	false	Automatically update listings when package version changes
annotationThreshold	number	100	Minimum percentage of tools requiring annotations to pass
dryRun	boolean	false	Validate and report without actually submitting

Best Practices

1. Include Examples in Every Tool Definition Registry reviewers and consumers rely on usage examples to understand tool behavior. Provide at least one example input-output pair per tool in your mcp.json manifest. This accelerates approval and improves discovery ranking.

2. Declare All Capabilities Including Optional Ones Even if your server has partial completions support, declare the capability with a note about coverage. Registries index capabilities for search, so undeclared capabilities make your server invisible to filtered queries.

3. Maintain a Changelog Alongside Metadata Updates When updating registry listings for a new version, include a concise changelog entry. This helps registry maintainers approve updates faster and gives consumers confidence in what changed between versions.

4. Use Semantic Versioning Strictly Breaking changes to tool schemas or removed capabilities require a major version bump. Registries may flag servers that introduce breaking changes under a minor or patch version, damaging your trust score.

5. Test Metadata Against Multiple Registry Schemas Each registry may enforce slightly different metadata requirements. Validate your mcp.json against each target registry's schema before submission to avoid rejection and rework cycles.

Common Issues

1. Publication rejected due to incomplete tool annotations Many registries now require annotations on all tools that perform write or delete operations. Review your tool definitions and add appropriate annotations (destructive, read-only, idempotent) before resubmitting.

2. Version mismatch between npm package and registry listing The registry shows an older version because auto-sync is not configured. Manually trigger a metadata update after each npm publish, or enable the autoSyncVersions parameter to handle this automatically.

3. Registry search does not surface your recently published server Indexing delays of up to 24 hours are common. Additionally, verify your server has a meaningful description, relevant tags, and at least one verified transport. Sparse metadata causes low ranking in search results even after indexing completes.