# proxy-mcp

Universal MCP proxy server that discovers, searches, and executes tools across all your configured MCP servers from a single entry point.

## Features

- **Proxy execution** — Call any tool on any MCP server through `execute_mcp_tool`
- **Semantic search** — Find tools by describing what you want to do, not by exact name
- **Connection pool** — MCP subprocesses are spawned on-demand and reused across calls
- **Weight learning** — The search system learns from your selections to improve rankings over time
- **Auto-indexing** — All MCP tools are indexed on server startup (non-blocking)

## Tools

| Tool | Description |
|------|-------------|
| `execute_mcp_tool` | Execute any tool on any configured MCP server |
| `search_tools` | Semantic search across all indexed tools |
| `list_available_mcps` | List configured MCP servers and their status |
| `refresh_tool_index` | Re-index tools from MCP servers |
| `get_learned_weights` | View learned search weights |
| `reset_learned_weights` | Reset all learned weights |
| `close_mcp_connections` | Close all active MCP connections |

## Requirements

- Python >= 3.10
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Installation

```bash
# Clone
git clone https://github.com/Rixmerz/proxy-mcp.git
cd proxy-mcp

# Install with uv
uv sync
```

## Configuration

Add to `~/.claude.json` under `mcpServers`:

```json
{
  "mcpServers": {
    "proxy-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxy-mcp", "proxy-mcp"]
    }
  }
}
```

The proxy reads MCP server configs from:
1. `~/.agentcockpit/mcps.json` (priority)
2. `~/.claude.json` (fallback)

## Usage examples

```
# Search for a tool by what you want to do
search_tools(query="expose service to internet")

# Execute a tool on a specific MCP
execute_mcp_tool(
    mcp_name="Context7",
    tool_name="get-library-docs",
    arguments={"context7CompatibleLibraryID": "/vercel/next.js", "topic": "routing"}
)

# List all available MCPs
list_available_mcps()
```

## Data

Learned weights are stored at `~/.proxy-mcp/learned_weights.json`.

## License

MIT