MCP Discovery Tool

Programmatically discover and catalog the capabilities of Model Context Protocol (MCP) servers.

The MCP Discovery Tool is itself an MCP server that exposes a powerful discoverMCPCapabilities tool. This tool can connect to any MCP-compliant server, interrogate it for its capabilities, and return comprehensive metadata including tools, prompts, resources, and detailed usage information.

🌟 Features

• 🔍 Comprehensive Discovery: Automatically discovers tools, prompts, and resources from any MCP server
• 🚀 Multi-Server Support: Discover multiple servers in parallel for efficiency
• 📊 Enhanced Metadata: Provides usage guidance, parameter details, and JSON schemas
• 🛡️ Robust Error Handling: Gracefully handles failures with detailed error information
• 🔧 Flexible Configuration: Support for config files, inline JSON, or direct server specs
• 🌐 Cross-Platform: Works on Windows, macOS, and Linux
• ⚡ Multiple Server Types: Supports Node.js (npx/node), Python, and custom executables
• 🔒 Type-Safe: Built with TypeScript for full type safety

📦 Installation

npm install
npm run build

🚀 Quick Start

As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop, VS Code):

{
  "mcpServers": {
    "discovery": {
      "command": "node",
      "args": ["path/to/mcp-discovery-tool/dist/index.js"]
    }
  }
}

Or use npx for direct execution:

{
  "mcpServers": {
    "discovery": {
      "command": "npx",
      "args": ["-y", "tsx", "path/to/mcp-discovery-tool/src/index.ts"]
    }
  }
}

📖 Usage

The discoverMCPCapabilities Tool

Once the MCP Discovery Tool is running as an MCP server, you can call its discoverMCPCapabilities tool to discover other servers.

Option 1: Discover from Configuration File

Configuration File (mcp-servers.json):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Tool Call:

{
  "name": "discoverMCPCapabilities",
  "arguments": {
    "configPath": "./mcp-servers.json"
  }
}

Option 2: Discover Single Server

Tool Call:

{
  "name": "discoverMCPCapabilities",
  "arguments": {
    "serverSpec": {
      "name": "memory",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Option 3: Discover with Inline JSON Configuration

Tool Call:

{
  "name": "discoverMCPCapabilities",
  "arguments": {
    "configJson": "{\"mcpServers\":{\"memory\":{\"command\":\"npx\",\"args\":[\"-y\",\"@modelcontextprotocol/server-memory\"]}}}"
  }
}

Option 4: Filtered Discovery

Discover only specific servers from a configuration:

{
  "name": "discoverMCPCapabilities",
  "arguments": {
    "configPath": "./mcp-servers.json",
    "servers": ["memory"],
    "timeout": 15000
  }
}

🔧 Tool Parameters

Configuration Sources (Choose ONE)

| Parameter | Type | Description | |-----------|------|-------------| | configPath | string | Path to JSON configuration file containing MCP server definitions | | configJson | string | Inline JSON string with MCP server configuration | | serverSpec | object | Single server specification for quick discovery |

Discovery Options

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | servers | string[] | - | Filter to specific server names from configuration | | parallel | boolean | true | Discover servers in parallel (false for sequential) | | timeout | number | 30000 | Timeout per server in milliseconds | | includeResources | boolean | true | Include resource details in output | | includeSchema | boolean | true | Include full JSON schemas for tools |

📊 Output Format

The tool returns an array of DiscoveryResult objects, one per server:

[
  {
    "serverName": "memory",
    "serverInfo": {
      "name": "@modelcontextprotocol/server-memory",
      "version": "1.0.0",
      "protocolVersion": "2024-11-05",
      "capabilities": {
        "tools": {}
      }
    },
    "tools": [
      {
        "name": "create_memory",
        "description": "Create a new memory with text content",
        "inputSchema": {
          "type": "object",
          "properties": {
            "content": {
              "type": "string",
              "description": "Text content to remember"
            }
          },
          "required": ["content"]
        },
        "whenToUse": "Use this tool when you need to create or write a new memory with text content",
        "parameters": [
          {
            "name": "content",
            "type": "string",
            "description": "Text content to remember",
            "required": true
          }
        ],
        "requiredParameters": ["content"]
      }
    ],
    "prompts": [],
    "resources": [],
    "discoveredAt": "2025-10-04T10:30:00.000Z",
    "discoveryDuration": 2543
  }
]

DiscoveryResult Fields

| Field | Type | Description | |-------|------|-------------| | serverName | string | Server name from specification | | serverInfo | object | Server metadata (name, version, protocol, capabilities) | | tools | array | Enhanced tool information with usage guidance | | prompts | array | Prompt information with arguments | | resources | array | Resource information with URIs and types | | errors | array | Errors encountered during discovery (if any) | | discoveredAt | string | ISO timestamp of discovery | | discoveryDuration | number | Discovery duration in milliseconds |

Enhanced Tool Information

Each tool includes:

• name: Tool identifier
• description: What the tool does
• inputSchema: Full JSON Schema for parameters
• whenToUse: Usage guidance (automatically inferred)
• parameters: Extracted parameter details
• requiredParameters: List of required parameter names

🔒 Server Configuration Format

{
  "mcpServers": {
    "server-name": {
      "command": "npx | node | python | python3 | <custom>",
      "args": ["array", "of", "arguments"],
      "env": {
        "OPTIONAL": "environment variables"
      },
      "cwd": "/optional/working/directory"
    }
  }
}

Supported Server Types

Node.js (via npx)

{
  "memory": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-memory"]
  }
}

Node.js (local script)

{
  "custom": {
    "command": "node",
    "args": ["./dist/my-server.js"]
  }
}

Python

{
  "python-server": {
    "command": "python",
    "args": ["-m", "my_mcp_server"]
  }
}

Custom with Environment Variables

{
  "advanced": {
    "command": "npx",
    "args": ["-y", "my-mcp-server"],
    "env": {
      "API_KEY": "secret",
      "DEBUG": "true"
    },
    "cwd": "/path/to/working/dir"
  }
}

🎯 Use Cases

1. MCP Server Registry/Index

Build a searchable catalog of available MCP servers and their capabilities.

2. Automated Documentation

Generate documentation for MCP servers by discovering their tools and capabilities.

3. AI Agent Tool Discovery

Let AI agents dynamically discover what tools are available before performing tasks.

4. Server Validation

Validate that MCP servers expose the expected tools and schemas.

5. Development & Debugging

Quickly inspect server capabilities during development.

6. Tool Composition

Discover complementary tools across multiple servers for complex workflows.

🛠️ Development

Build

npm run build

Run in Development Mode

npm run dev

Project Structure

src/
├── index.ts                      # Main MCP server entry point
├── types/
│   ├── discovery.ts              # Type definitions
│   └── index.ts                  # Type exports
├── discovery/
│   ├── orchestrator.ts           # Discovery orchestration
│   ├── connection-manager.ts     # Server process management
│   ├── mcp-client.ts            # MCP client wrapper
│   └── metadata-aggregator.ts    # Metadata enhancement
└── utils/
    └── config-parser.ts          # Configuration parsing

🔍 How It Works

1. Parse Configuration: Reads server specifications from file, JSON, or direct spec
2. Validate Specs: Validates command safety and argument structure
3. Spawn Servers: Starts each server process with appropriate command/args
4. Connect via Stdio: Establishes MCP protocol connection over stdio
5. Initialize Protocol: Performs MCP handshake to get server info
6. Discover Capabilities: Calls listTools(), listPrompts(), listResources()
7. Enhance Metadata: Adds usage guidance and extracts parameter details
8. Cleanup: Gracefully disconnects and terminates server processes
9. Return Results: Aggregates all discoveries into structured response

⚠️ Error Handling

The tool handles errors gracefully:

• Connection Failures: Returns error result for that server, continues with others
• Timeouts: Configurable per-server timeout (default 30s)
• Partial Failures: If one server fails, others still succeed
• Detailed Errors: Error messages include type, message, and details

Example error result:

{
  "serverName": "problematic-server",
  "serverInfo": null,
  "tools": [],
  "prompts": [],
  "resources": [],
  "errors": [
    {
      "type": "connection",
      "message": "Failed to spawn process: command not found",
      "details": {
        "command": "npx",
        "args": ["-y", "@missing/package"],
        "error": "ENOENT"
      }
    }
  ],
  "discoveredAt": "2025-10-04T10:30:00Z",
  "discoveryDuration": 5000
}

🔐 Security Considerations

Command Validation

• Commands are validated against an allowed list
• Potentially dangerous arguments are detected
• Full command logging for audit trails

Process Isolation

• Each server runs in its own process
• Configurable timeouts prevent hangs
• Automatic cleanup on errors

Configuration Trust

• User must explicitly provide configuration
• No automatic execution of unknown code
• Warning for non-standard commands

🚦 Cross-Platform Support

The MCP Discovery Tool works seamlessly across Windows, macOS, and Linux with no platform-specific configuration required!

✅ Key Compatibility Features

• Zero Platform-Specific Code: Works identically on all platforms
• Smart Process Spawning: Uses cross-spawn (via MCP SDK) to handle platform differences automatically
• Cross-Platform Commands: Use "npx" directly on all platforms—no need for cmd /c on Windows!
• Path Normalization: Node.js automatically handles path separators
• Pure JavaScript: No native dependencies or platform-specific binaries

📋 Platform-Specific Notes

Windows

• ✅ npx, node, python commands work directly (no cmd /c wrapper needed)
• ✅ Automatically handles .cmd and .bat files
• ✅ Respects Windows environment variables (APPDATA, LOCALAPPDATA, etc.)

macOS

• ✅ Native Unix commands work out of the box
• ✅ Uses standard PATH resolution
• ✅ Full support for Python virtual environments

Linux

• ✅ All distributions supported (Ubuntu, Debian, Fedora, Arch, etc.)
• ✅ Works in Docker containers
• ✅ Compatible with WSL (Windows Subsystem for Linux)

💡 Cross-Platform Configuration Tips

✅ DO: Use commands available in PATH

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-memory"]
}

✅ DO: Use forward slashes or absolute paths

{
  "command": "node",
  "args": ["/home/user/server/index.js"]
}

❌ DON'T: Use platform-specific wrappers

{
  "command": "cmd",
  "args": ["/c", "npx", "..."]  // ❌ Unnecessary on Windows!
}

❌ DON'T: Use Windows-only paths in examples

{
  "args": ["C:\\Program Files\\server\\index.js"]  // ❌ Won't work on macOS/Linux
}

🧪 Tested Platforms

| Platform | Node.js Version | Status | |----------|----------------|--------| | Windows 10/11 | 18.x, 20.x, 22.x | ✅ Tested | | macOS 12+ | 18.x, 20.x, 22.x | ✅ Compatible | | Ubuntu 20.04+ | 18.x, 20.x, 22.x | ✅ Compatible | | Debian 11+ | 18.x, 20.x, 22.x | ✅ Compatible | | WSL 2 | 18.x, 20.x, 22.x | ✅ Compatible |

📝 Examples

See the examples/ directory for:

• mcp-servers-config.json - Multi-server configuration
• single-server-example.json - Single server discovery
• multi-server-example.json - Parallel multi-server discovery
• filtered-discovery-example.json - Filtered discovery

🤝 Contributing

Contributions welcome! This tool is designed to be extensible:

• Add new transport support (HTTP/SSE)
• Enhance usage guidance generation
• Improve error messages
• Add caching mechanisms
• Build visualization tools

📄 License

MIT

🙏 Acknowledgments

Built using:

• @modelcontextprotocol/sdk - Official MCP TypeScript SDK
• TypeScript - Type-safe implementation
• Node.js - Runtime environment

Need help? Check the examples or file an issue on GitHub.

Want to extend? The modular architecture makes it easy to add features!