> ## Documentation Index
> Fetch the complete documentation index at: https://condor.hummingbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP & Tools

> Model Context Protocol servers that connect Trading Agents to Hummingbot API

Trading Agents interact with exchanges and local operations through **MCP (Model Context Protocol)** servers. MCP provides a standardized way for LLMs to call tools via JSON-RPC 2.0.

## Architecture

Condor runs two MCP servers:

| Server | Purpose |
| - | - |
| **hummingbot-mcp** | Trading operations via Hummingbot API (13 tools) |
| **condor-mcp** | Local operations: skills, domain agents, memory, notifications, routines, journals |

```mermaid theme={null}
flowchart LR
    Agent[Trading Agent] --> |JSON-RPC| HMCP[hummingbot-mcp]
    Agent --> |JSON-RPC| CMCP[condor-mcp]
    HMCP --> API[Hummingbot API]
    API --> Exchanges[CEXs & DEXs]
    CMCP --> Local[Local Files]
    CMCP --> TG[Telegram]
```

## Hummingbot MCP Tools

### Account Management

| Tool | Description |
| - | - |
| `setup_connector()` | Add/remove exchange API credentials |
| `configure_server()` | Switch between Hummingbot API servers |

### Portfolio & Holdings

| Tool | Description |
| - | - |
| `get_portfolio_overview()` | Unified view: balances, positions, LP, orders |

### Trading Operations

| Tool | Description |
| - | - |
| `set_account_position_mode_and_leverage()` | Configure perpetual trading settings |
| `search_history()` | Query historical orders, positions, LP |
| `get_market_data()` | Prices, candles, funding rates, order books |

### Executor Management

The primary trading interface for agents:

| Tool | Description |
| - | - |
| `manage_executors()` | Create, search, stop trading executors |

**Supported executor types:**

* `order_executor` - Single limit/market orders
* `position_executor` - Directional trades with triple barrier
* `grid_executor` - Multi-level grid trading
* `dca_executor` - Dollar-cost averaging
* `lp_executor` - Liquidity provision

**Actions:** `create`, `search`, `stop`, `get_logs`

### Bot Management

For advanced multi-strategy deployments:

| Tool | Description |
| - | - |
| `manage_bots()` | Deploy and control controller-based bots |
| `manage_controllers()` | CRUD operations on controller templates |

### Market Data & Discovery

| Tool | Description |
| - | - |
| `explore_dex_pools()` | Discover DEX/CLMM pools with filtering |
| `explore_geckoterminal()` | Free market data: networks, pools, OHLCV |

### Backtesting

| Tool | Description |
| - | - |
| `run_backtest()` | Backtest a V2 controller config over historical data |
| `manage_backtest_tasks()` | Track and manage backtest tasks |

<Note>
  DEX liquidity positions are created through `manage_executors()` (the `lp_executor` type), and Gateway itself is managed from the Condor dashboard (**Settings → Gateway**) rather than through a dedicated MCP tool.
</Note>

## Condor MCP Tools

### Skills and domain agents

The routing model, and the part most worth knowing: before reaching for a raw
tool, an assistant looks for a **skill** (a playbook, sometimes bound to a
runnable routine) and then for a **domain agent** to hand the work to.

| Tool | Description |
| - | - |
| `manage_skill()` | Read, search, list, create, edit and delete skills. Skills belong to the assistant, not to a user — they are the shared playbooks everyone using it gets |
| `consult()` | Ask a domain agent a question and block for its answer. The agent runs in the main process, where the runtime and server credentials live, and may pause on a user confirmation before acting |
| `delegate()` | The unattended sibling of `consult()`. Hands a goal-oriented task to a detached agent that runs until done and then notifies the user; returns a `task_id` to poll or stop |

<Note>
  Authoring or debugging a **routine** goes through `delegate()` to a background
  Condor worker rather than being written by hand — the worker reads the routine
  cookbook, writes the routine, tests it, and reports back. Running an existing
  routine is not authoring: that is just `manage_routines()`.
</Note>

### Memory and code

| Tool | Description |
| - | - |
| `manage_memory()` | What the assistant remembers about *you*. Per-user, keyed to the calling user, with the writing agent recorded for audit |
| `run_code()` | Ad-hoc Python in the bot process, with the same primitives a routine gets — `context`, `client`, pandas, report builders, every `condor.*` module. The scratchpad below a routine: a snippet that failed is stored whole, read back, corrected and re-run |

<Warning>
  `run_code()` executes arbitrary Python inside the bot process. Granting it to
  a non-admin is the `code_run` permission in **Settings → Admin**, which spells
  out what it reaches before you grant it.
</Warning>

### Notifications and routines

| Tool | Description |
| - | - |
| `send_notification()` | Send Telegram messages (Markdown/HTML) |
| `manage_routines()` | Discover, run, create and edit routines |

### Trading agent operations

| Tool | Description |
| - | - |
| `manage_trading_agent()` | Strategy CRUD and agent lifecycle (start/stop/pause) |
| `trading_agent_journal_read()` | Read the journal: recent entries, learnings, state |
| `trading_agent_journal_write()` | Write to the journal: actions, learnings, state |

### Environment

| Tool | Description |
| - | - |
| `manage_servers()` | List accessible API servers |
| `get_user_context()` | Current user, active server, permissions |
| `get_available_models()` | Which models and providers are actually usable right now — installed CLI bridges, cloud keys present, reachable local servers and what they have loaded. Read-only, and never returns a key value, only whether its variable is set |
| `manage_notes()` | Key-value persistent storage |

## Progressive Disclosure

Many tools support step-by-step discovery:

```
1. Call with no parameters → See available options
2. Call with partial parameters → See next steps
3. Call with all parameters → Execute action
```

**Example: Creating an executor**

```
Agent: manage_executors()
Tool: Available executor types: order_executor, position_executor, grid_executor...

Agent: manage_executors(action="create", executor_type="grid_executor")
Tool: Required fields for grid_executor:
  - connector_name (string)
  - trading_pair (string)
  - ...

Agent: manage_executors(action="create", executor_type="grid_executor", config={...})
Tool: Grid executor created (ID: exec_123)
```

## Configuration

### Server Settings

MCP servers read configuration from environment variables or `~/.hummingbot_mcp/server.yml`:

| Variable | Default | Description |
| - | - | - |
| `HUMMINGBOT_API_URL` | `http://localhost:8000` | API server URL |
| `HUMMINGBOT_USERNAME` | `admin` | API username |
| `HUMMINGBOT_PASSWORD` | `admin` | API password |
| `HUMMINGBOT_TIMEOUT` | `30.0` | Request timeout (seconds) |
| `HUMMINGBOT_MAX_RETRIES` | `3` | Retry attempts |

### Runtime Configuration

Agents can switch servers at runtime:

```
Agent: configure_server()
Tool: Current server: localhost:8000 (admin)

Agent: configure_server(url="http://prod-server:8000", username="trader", password="xxx")
Tool: Connected to prod-server:8000
```

## Error Handling

MCP servers provide contextual error messages:

* **Connection errors**: Suggests checking server URL and Docker networking
* **Auth errors**: Prompts to verify credentials via `configure_server()`
* **Validation errors**: Shows required fields and valid values

All tools use retry logic (3 attempts with 2-second delays) for transient failures.

## Running MCP Servers

MCP servers are started automatically when agents launch via ACP. For manual testing:

```bash theme={null}
# Hummingbot MCP
python -m mcp_servers.hummingbot_api

# Condor MCP
python -m mcp_servers.condor
```

## Adding Custom Tools

To add tools to an MCP server, create a function with the `@mcp.tool()` decorator:

```python theme={null}
# In mcp_servers/hummingbot_api/tools/custom.py

@mcp.tool()
async def my_custom_tool(param1: str, param2: int = 10) -> str:
    """
    Description of what this tool does.

    Args:
        param1: Description of param1
        param2: Description of param2 (default: 10)
    """
    # Implementation
    result = await do_something(param1, param2)
    return format_result(result)
```

Register the tool in `server.py`:

```python theme={null}
from .tools.custom import my_custom_tool
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.