Agent (Claude Desktop, Cursor, Claude Code, etc.)
  │  Sees only: search_tools, get_tool_schema, call_tool
  ▼
MCPFind Proxy
  ├── Vector search over all tool descriptions
  ├── Per-agent MFU cache for personalized ranking
  └── Routes calls to the correct backend server
  │
  ├──▶ Gmail MCP Server
  ├──▶ GitHub MCP Server
  ├──▶ Slack MCP Server
  └──▶ ... N servers

# With uv (recommended)
uv tool install mcpfind

# With pip
pip install mcpfind

mcpfind setup

[proxy]
# Uses local embeddings by default — no API key needed
embedding_provider = "local"          # or "openai"
embedding_model = "all-MiniLM-L6-v2"  # or "text-embedding-3-small" for openai
mfu_boost_weight = 0.15
mfu_persist = true
default_max_results = 5

[[servers]]
name = "github"
command = "uvx"
args = ["mcp-server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }

[[servers]]
name = "filesystem"
command = "uvx"
args = ["mcp-server-filesystem", "/path/to/allowed/dir"]

# List all tools discovered from your backend servers
mcpfind list-tools --config mcpfind.toml

# Test semantic search
mcpfind search "create a pull request" --config mcpfind.toml

mcpfind serve --config mcpfind.toml

[[servers]]
name = "gmail"              # Unique name (used in search results and call_tool)
command = "uvx"              # Command to launch the server
args = ["mcp-gmail"]         # Arguments passed to the command
env = { GMAIL_TOKEN = "${GMAIL_TOKEN}" }  # Environment variables (supports ${VAR} expansion)

[[servers]]
name = "github"
command = "uvx"
args = ["mcp-server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }

[[servers]]
name = "filesystem"
command = "uvx"
args = ["mcp-server-filesystem", "/home/user/documents"]

[[servers]]
name = "slack"
command = "uvx"
args = ["mcp-server-slack"]
env = { SLACK_BOT_TOKEN = "${SLACK_BOT_TOKEN}" }

[[servers]]
name = "my-server"
command = "python"
args = ["-m", "my_mcp_server"]
env = { MY_API_KEY = "${MY_API_KEY}" }

{
  "mcpServers": {
    "mcpfind": {
      "command": "mcpfind",
      "args": ["serve", "--config", "/path/to/mcpfind.toml"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

{
  "mcpServers": {
    "mcpfind": {
      "command": "mcpfind",
      "args": ["serve", "--config", "/path/to/mcpfind.toml"]
    }
  }
}

{
  "mcpServers": {
    "mcpfind": {
      "command": "mcpfind",
      "args": ["serve", "--config", "/path/to/mcpfind.toml"]
    }
  }
}

Agent: search_tools("send an email")
  → [{"server": "gmail", "name": "send_email", "score": 0.94}, ...]

Agent: get_tool_schema(server="gmail", tool="send_email")
  → {"type": "object", "properties": {"to": ..., "subject": ..., "body": ...}}

Agent: call_tool(server="gmail", tool="send_email", arguments={...})
  → "Email sent!"

[proxy]
embedding_provider = "local"                # "local" (default) or "openai"
embedding_model = "all-MiniLM-L6-v2"        # Model name (provider-specific)
mfu_boost_weight = 0.15                     # Frequency boost weight (0.0-1.0)
mfu_persist = true                          # Persist usage data to SQLite
default_max_results = 5                     # Default number of search results

[[servers]]
name = "server-name"     # Required: unique identifier
command = "command"       # Required: executable to launch
args = ["arg1", "arg2"]  # Optional: command arguments
env = { KEY = "value" }  # Optional: environment variables (${VAR} expansion supported)

# Interactive setup wizard
mcpfind setup

# Start the proxy server (stdio MCP transport)
mcpfind serve --config mcpfind.toml

# List all discovered tools from backend servers
mcpfind list-tools --config mcpfind.toml

# Test semantic search
mcpfind search "query" --config mcpfind.toml --max-results 10

# Clone and install
git clone https://github.com/jcgs2503/mcp-lens.git
cd mcp-lens
uv sync

# Run tests
uv run pytest -v

# Lint and format
uv run ruff check .
uv run black --check .