Tooldex

🔭 Tooldex

Unified MCP Server Observatory — autodiscover, inspect, and monitor Model Context Protocol tools across Claude Code, Cursor, Codex, VSCode, Copilot, Gemini, Agents, and Docker

PyPI version Downloads License: MIT Python 3.12+

Questions, feedback, or just want to say hi? → Contact the Dev · banerjeeria2406@gmail.com

Tooldex autodiscovers MCP servers configured across your AI clients — Claude Code, Cursor, Codex, VSCode, Copilot, Gemini (Antigravity), Agents, Docker MCP Toolkit — and surfaces every exposed tool in a unified UI with a live REST API. No manual config. Run it from any project directory and it finds everything.

⚠️ Tool Poisoning Attacks are real. A malicious MCP server can expose dozens of legitimate tools and hide one bad one. Tooldex gives you full visibility into your MCP tool surface before anything executes — essential for any agentic AI environment.

Tooldex Demo

Why Tooldex?

As your agentic AI setup grows across distributed systems and multiple clients, you lose track of what MCP servers are running and what tools they expose. Tooldex fixes that:

Contents

Requirements

Installation

pip install tooldex

Verify:

tooldex --version

Quick start

cd your-project
tooldex run

Tooldex scans config files, probes each discovered server for its tool surface, and opens the UI. The startup banner shows where to connect:

  ╔══════════════════════════════════════════════════╗
  ║         tooldex  v1.0.1                         ║
  ╠══════════════════════════════════════════════════╣
  ║  Servers  12                                     ║
  ║  Tools    187                                    ║
  ╠══════════════════════════════════════════════════╣
  ║  →  http://127.0.0.1:8282                        ║
  ╚══════════════════════════════════════════════════╝

To see the discovery summary without starting the server:

tooldex run --no-serve

How discovery works

When you run tooldex run, the following happens in order:

  1. Config scan — Tooldex reads every known MCP config location for the current directory (see Config file locations). Each found server gets a qualified ID in the form {client}:{server_name} so servers from different clients never collide.

  2. Live probe — Each discovered server is contacted concurrently. Tooldex calls tools/list on it and records which tools it exposes, how long it took, and any errors.

  3. Deduplication — If the same server name appears in multiple clients (e.g., browserbase in both Claude Code and Cursor), both are retained as separate entries under their respective clients. Duplicate server names across clients are reported in the duplicates field.

  4. UI — A local web server starts and serves the unified view.

Config file locations

Tooldex checks all of the following on every run. Files that do not exist are skipped silently.

Claude Code

Scope Path
Global ~/.claude.json
Project <project>/.claude/mcp.json
Project (flat) <project>/.claude.json

Cursor

Scope Path
Global ~/.cursor/mcp.json
Project <project>/.cursor/mcp.json

Codex CLI

Scope Path
Global ~/.codex/config.toml
Project <project>/.codex/config.toml

VSCode

Scope Path
Workspace <project>/.vscode/mcp.json
Workspace <project>/.vscode/.mcp.json
User (global) ~/.config/Code/User/mcp.json

VSCode nests servers under a top-level "servers" key rather than "mcpServers" — Tooldex parses that shape natively, no config changes needed on your end. ${input:...} placeholders (VSCode’s prompted-variable syntax) are left untouched since Tooldex doesn’t drive VSCode’s input UI; standard ${VAR} / $VAR env references still resolve normally. All three paths are scanned independently — if more than one exists, servers from each are merged in.

Copilot CLI

Scope Path
Global ~/.copilot/mcp-config.json

GitHub Copilot CLI’s own config — separate from VSCode’s Copilot chat extension above. Unlike VSCode, it uses the standard "mcpServers" key (same shape as Claude/Cursor), with a "type": "local" transport field and an optional "tools" allowlist array that Tooldex doesn’t currently filter on — all of a server’s discovered tools are shown regardless of what’s listed there.

MCP JSON (shared / team configs)

Scope Path
Global ~/.mcp.json
Project <project>/.mcp.json
Project (bare) <project>/mcp.json

Agents

Scope Path
Global ~/.agents/mcp.json
Global ~/.agents/.mcp.json
Project <project>/.agents/mcp.json
Project <project>/.agents/.mcp.json

Gemini (Antigravity IDE)

Scope Path
Global ~/.gemini/antigravity/mcp_config.json

Docker MCP Toolkit

Tooldex reads all Docker MCP profiles via docker mcp profile ls. No additional configuration is needed.

Project-scoped paths are discovered by walking up the directory tree from cwd until the home directory. This means running tooldex run from a nested subdirectory will still find config files at the project root. Both mcp.json and .mcp.json are checked at every level of the walk.

MCP config format

All JSON-based clients use the same mcpServers structure. Tooldex understands both stdio (command-based) and http/sse (URL-based) transports.

Comments are supported. Tooldex parses JSON5, so // line comments and /* block */ comments in config files are handled gracefully — no need to strip them before running.

stdio server (runs a local process)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {
        "SOME_VAR": "value"
      }
    },
    "my-db-server": {
      "command": "node",
      "args": ["/path/to/my-server/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432"
      }
    }
  }
}

HTTP / SSE server (connects to a remote endpoint)

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    },
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse"
    }
  }
}

Codex (~/.codex/config.toml)

Codex uses TOML with an [mcp_servers.<id>] table per server:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

[mcp_servers.github]
type = "http"
url = "https://api.githubcopilot.com/mcp/"

What Tooldex detects from these files

For each config file found, Tooldex reports:

For each server probed:

CLI reference

tooldex [OPTIONS] COMMAND [ARGS]

Global options

Flag Description
--version, -V Print version and exit
--help, -h Show help

tooldex run

Autodiscover MCP servers and start the UI.

tooldex run [OPTIONS]
Flag Default Description
--port, -p 8282 Starting port. Increments automatically if occupied.
--host 127.0.0.1 Interface to bind the UI server to.
--no-serve off Print discovery summary and exit without starting the server.
--json off Print discovery result as JSON and exit. Implies --no-serve. Does not probe servers.
--timeout 10.0 Per-server probe timeout in seconds.
--concurrency 8 Maximum concurrent server probes.
--no-probe <name> — Skip probing a specific server by name. Repeatable.
--config <path> — Additional MCP config file to include. Repeatable. Custom configs are processed first and win on duplicate server IDs.
--no-cache off Bypass the probe cache and re-probe every server live.
--no-security-scan off Skip the automatic YARA security scan (see Security scanning). Equivalent to TOOLDEX_SECURITY_SCAN=false, and also applies to later “rescan all” calls for the life of this server.

All flags accept both --flag and -flag prefix.

Examples

# Discover and launch UI
tooldex run

# Custom port and host
tooldex run --port 9000 --host 0.0.0.0

# Just print what was found, don't start the server
tooldex run --no-serve

# Skip slow or broken servers during probing
tooldex run --no-probe node-api-docs --no-probe local-mcp

# Include an extra config file
tooldex run --config ~/shared/team-servers.json

# Increase timeout for slow servers
tooldex run --timeout 30

# Use all 16 cores for probing
tooldex run --concurrency 16

# Pipe the discovery result into jq
tooldex run --json | jq '.duplicates'

# Force a live re-probe of every server, ignoring the probe cache
tooldex run --no-cache

# Skip the automatic YARA security scan entirely
tooldex run --no-security-scan

JSON output

tooldex run --json prints a single JSON object to stdout and exits. No servers are probed; this is fast and side-effect-free for use in scripts and CI.

{
  "sources": [
    {
      "client": "claude_code_user",
      "path": "/home/user/.claude.json",
      "status": "found",
      "error": null,
      "server_ids": ["filesystem", "github"],
      "in_file_duplicates": []
    },
    {
      "client": "mcp_json_user",
      "path": "/home/user/.mcp.json",
      "status": "not_found",
      "error": null,
      "server_ids": [],
      "in_file_duplicates": []
    }
  ],
  "servers": {
    "claude_code_user:filesystem": {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "url": null
    }
  },
  "duplicates": [
    "\"filesystem\" in cursor_user is also configured in claude_code_user",
    "\"firecrawl-mcp\" is a duplicate key in /home/user/.mcp.json (last value kept)"
  ]
}

Fields:

Field Description
sources Every config location checked, with status and server IDs found.
servers Deduplicated map of all servers, keyed by {client}:{server_id}.
duplicates Human-readable notes about server name collisions across clients, and duplicate JSON keys within a single file.

Exit codes: 0 on success, 1 on serialisation error.

Security scanning

Powered by Cisco’s MCP Scanner (mcpscanner on PyPI) — Tooldex wraps it, it doesn’t reimplement it.

YARA scan (always on)

Runs automatically as part of every discovery and rescan, for every server. Local, free, no API key required, no configuration needed.

Every server is connected to twice per discovery/rescan — once by Tooldex’s own discovery probe (to call tools/list and populate the UI), and once independently by mcpscanner’s Scanner (to fetch tool metadata for YARA analysis). These are two separate connections/process launches; mcpscanner doesn’t expose a way to reuse tools Tooldex has already fetched. If the same server name is configured in multiple clients (e.g. both VSCode and Copilot CLI), each client’s copy is scanned separately, so you may see more than 2 connections total for that server name.

Env var Description Default
TOOLDEX_SECURITY_SCAN Set to false to disable the automatic YARA scan entirely (both at startup and on later “rescan all” calls). Same as passing --no-security-scan. true
MCP_SCANNER_CONCURRENCY Maximum concurrent YARA scan calls. Distinct from run’s --concurrency flag, which controls tool-probing concurrency, not scanning. 8

--no-security-scan and TOOLDEX_SECURITY_SCAN=false are equivalent — either one disables the scan (the flag works by setting that env var for the process). Whenever the scan is skipped, Tooldex prints the reason to the CLI:

Security scan skipped — --no-security-scan flag was passed.
Security scan skipped — TOOLDEX_SECURITY_SCAN is set to false.

AI security scan (LLM-as-judge, opt-in)

Tooldex’s AI security scan is powered by Cisco AI Defense’s open-source mcpscanner SDK, running entirely locally — the only network call it makes is to whichever LLM provider you configure.

An LLM reviews each tool’s name, description, and input schema for malicious intent (data exfiltration, prompt injection, tool poisoning, etc.). Unlike YARA, this never runs automatically — it’s triggered manually per server, from the UI (“AI security scan” button) or via POST /api/servers/{id}/llm-scan/.

Requires TOOLDEX_LLM_API_KEY at minimum. Without it, the AI security scan is simply unavailable — YARA scanning is unaffected.

Env var Legacy fallback Description Default
TOOLDEX_LLM_API_KEY MCP_SCANNER_LLM_API_KEY API key for your LLM provider (OpenAI, Anthropic, etc). Required to enable the AI security scan. (unset — scan disabled)
TOOLDEX_LLM_MODEL MCP_SCANNER_LLM_MODEL Model to use, e.g. gpt-4o, claude-3-5-sonnet-latest gpt-4o
TOOLDEX_LLM_RATE_LIMIT_DELAY MCP_SCANNER_LLM_RATE_LIMIT_DELAY Seconds to wait between LLM calls 2.0
TOOLDEX_LLM_TEMPERATURE MCP_SCANNER_LLM_TEMPERATURE Sampling temperature 1.0
TOOLDEX_LLM_MAX_RETRIES MCP_SCANNER_LLM_MAX_RETRIES Max retries on a failed LLM call 6
TOOLDEX_LLM_BASE_URL MCP_SCANNER_LLM_BASE_URL Custom endpoint (Azure OpenAI, self-hosted Ollama/vLLM/LocalAI, etc.) (unset)
TOOLDEX_LLM_API_VERSION MCP_SCANNER_LLM_API_VERSION API version, e.g. required by Azure OpenAI (unset)
TOOLDEX_LLM_TIMEOUT MCP_SCANNER_LLM_TIMEOUT Per-request LLM timeout in seconds 30

Every TOOLDEX_LLM_* var also accepts its original mcpscanner name (MCP_SCANNER_LLM_*) as a fallback if the TOOLDEX_LLM_* one isn’t set — an existing mcpscanner-native setup keeps working un-migrated. Using a legacy name prints a one-time notice on the CLI pointing at the rename.

MCP_SCANNER_API_KEY (Cisco’s separate cloud API) and VIRUSTOTAL_API_KEY are not supported — Tooldex only uses mcpscanner’s local YARA and LLM analyzers.

Model support: any LiteLLM-compatible model string works, since the LLM analyzer runs through LiteLLM internally — there’s no fixed allowlist. TOOLDEX_LLM_MODEL defaults to gpt-4o if unset.

Caching: results are cached per-server, per-tool at ~/.tooldex/llm_scan_cache.json, fingerprinted by a hash of each tool’s name, description, and input schema — a cache entry is invalidated automatically the moment that tool’s identity changes, with no TTL otherwise.

API endpoints

When the server is running (default http://127.0.0.1:8282):

All endpoints respond with or without a trailing slash.

Method Endpoint Description
GET /api/health/ status, current timestamp, and uptime_seconds since the server started
GET /api/servers/ All MCP servers with total_servers, total_tools, scanned_at. Per server: tool_count, source_file, has_llm_cache, and the security_* fields below
GET /api/servers/{id}/ Single server with full tool detail
POST /api/servers/{id}/rescan/ Re-probe a single server, update its tools in place, and (if the probe succeeds and TOOLDEX_SECURITY_SCAN isn’t disabled) re-run its YARA scan too, so security_scanned/security_risk stay current. force=true aborts an in-flight AI security scan on this server first; otherwise returns 409 {"error": "llm_scan_running"} while one is running
POST /api/servers/{id}/llm-scan/ Start the AI security scan for one server as a background job. force (default true) skips the cache and forces fresh LLM calls; results are cached either way
GET /api/servers/{id}/llm-scan/status/ Poll progress (scanned/total) and outcome of the AI security scan job for this server
POST /api/servers/{id}/llm-scan/stop/ Signal a running AI security scan to stop
POST /api/servers/{id}/llm-scan/invalidate-cache/ Clear cached AI scan results for this server and reset its displayed state to “not yet scanned”
GET /api/files/ All config files that were scanned: path, client, status, server IDs found, any parse errors
POST /api/rescan/ Full rediscovery — re-reads all MCP configs and re-probes every server. Returns {"status": "already_scanning"} if a rescan is already in progress.
GET /api/rescan/stream/ Same rediscovery as above, streamed as Server-Sent Events (one per server, then done). force=true aborts any in-flight AI security scans fleet-wide first; otherwise yields {"type": "blocked", "servers": [...]} and stops

Per-server security fields (on /api/servers/ and /api/servers/{id}/):

Field Description
security_findings List of findings from the last scan: {tool_name, severity, analyzer, threat_category, summary}
security_risk Worst severity across all findings — HIGH / MEDIUM / LOW / INFO / null
security_scanned true once this server has been included in a scan run
security_llm_scanned_at UTC ISO timestamp of the last AI security scan, if any
security_llm_new_findings Findings from the last AI scan not present in the one before it
security_llm_cache_hits Of the last AI scan’s tools, how many were served from cache rather than a real LLM call
security_llm_last_scan_total Total tools attempted in the last AI scan (cache hits + real calls)
has_llm_cache Whether any cached AI scan result exists for this server (drives the clear-cache icon)

Testing

Tooldex has a pytest unit-test suite that runs in CI on every PR:

pip install -e ".[test]"
pytest

See CONTRIBUTING.md for details. For ad-hoc manual checks against your own MCP config:

# Verify discovery against your local config
tooldex run --no-serve

# Inspect the raw discovery payload
tooldex run --json | jq .

# Check a specific extra config file
tooldex run --config ./my-config.json --json

# Confirm a server is reachable with a longer timeout
tooldex run --timeout 30 --no-probe github

To run the package from source without installing:

git clone <repo>
cd Tooldex
pip install -e .
tooldex --version

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup instructions, the development workflow, and pull request guidelines.

Contact the Dev

Have a bug report, feature request, or just want to share feedback? Reach out directly:

Email: banerjeeria2406@gmail.com

All feedback is welcome — whether it’s a quick note or a detailed suggestion.

This site is open source. Improve this page.