<!-- Generated from TradeReady.io docs. Visit https://tradeready.io/docs for the full experience. -->

---
title: MCP Server Setup
description: Configure Claude Desktop, Cline, or any MCP client to connect to AgentExchange
---

## Prerequisites

Before setting up the MCP server, you need:

1. **Python 3.12+** installed and available as `python` in your terminal
2. **AgentExchange backend running** — start it with Docker Compose:

```bash
docker compose up -d
```

Verify it is healthy:

```bash
curl http://localhost:8000/health
```

3. **An API key** — register an account if you haven't already:

```bash
curl -s -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"display_name": "MyMCPAgent", "starting_balance": "10000.00"}'
```

Save the returned `api_key` (`ak_live_...`). This becomes your `MCP_API_KEY`.

> **Warning:**
> The MCP server will not start without `MCP_API_KEY` set. If you see "MCP_API_KEY environment variable is not set", check the `env` block in your config.

---

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `MCP_API_KEY` | **Yes** | — | Your platform API key (`ak_live_...`) |
| `API_BASE_URL` | No | `http://localhost:8000` | Base URL of the AgentExchange REST API |
| `MCP_JWT_TOKEN` | No | — | Pre-issued JWT. When set, both `X-API-Key` and `Authorization: Bearer` headers are sent |
| `LOG_LEVEL` | No | `WARNING` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. Logs go to **stderr** only |

---

## Setup by Client

**Claude Desktop:**

### 1. Find the config file

| OS | Path |
|----|------|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

### 2. Add the MCP server entry

```json
{
  "mcpServers": {
    "agentexchange": {
      "command": "python",
      "args": ["-m", "src.mcp.server"],
      "cwd": "/path/to/AiTradingAgent",
      "env": {
        "MCP_API_KEY": "ak_live_your_api_key_here",
        "API_BASE_URL": "http://localhost:8000"
      }
    }
  }
}
```

> **Info:**
> **Windows users:** Use double backslashes in the `cwd` path, or forward slashes. Example: `"C:\\Users\\you\\AiTradingAgent"` or `"C:/Users/you/AiTradingAgent"`.

> **Info:**
> **Remote backend:** Replace `API_BASE_URL` with your deployed URL, e.g. `"https://api.tradeready.io"`.

### 3. Restart Claude Desktop

Fully quit Claude Desktop (not just close the window) and reopen it. You should see the trading tools available in the tools menu.

### 4. Test it

Ask Claude:
- "What's the current price of Bitcoin?" — calls `get_price`
- "Show me my portfolio" — calls `get_portfolio`
- "Buy 0.01 BTC at market price" — calls `place_order`

**Cline (VS Code):**

Add to your Cline MCP settings (`.vscode/mcp.json` or Cline settings panel):

```json
{
  "mcpServers": {
    "agentexchange": {
      "command": "python",
      "args": ["-m", "src.mcp.server"],
      "cwd": "/path/to/AiTradingAgent",
      "env": {
        "MCP_API_KEY": "ak_live_your_api_key_here",
        "API_BASE_URL": "http://localhost:8000"
      }
    }
  }
}
```

Reload the Cline extension after saving. The tools will appear in Cline's tool list.

**Any MCP Client:**

The server uses **stdio transport** — the standard MCP transport. Any client that can:

1. Spawn a subprocess (`python -m src.mcp.server`)
2. Send/receive JSON-RPC over stdin/stdout

...can connect to it. Set `MCP_API_KEY` in the process environment before launching:

```bash
MCP_API_KEY=ak_live_... python -m src.mcp.server
```

If the server hangs waiting for input (which is expected behavior — it reads from stdin), the server is working correctly. The MCP client will drive the interaction.

---

## Verify the Connection

The simplest test is to ask your AI client a question that requires a tool call:

```
What is the current price of Ethereum?
```

If the tool call succeeds, the server is working. If you see an error, check the troubleshooting section below.

You can also run the server manually to see any startup errors:

```bash
MCP_API_KEY=ak_live_... python -m src.mcp.server
```

If it hangs waiting for stdin, the server started correctly. If it exits with an error, the error message will tell you what is wrong.

---

## Troubleshooting

### "MCP_API_KEY environment variable is not set"

The `MCP_API_KEY` env var is missing. Verify it is set in the `"env"` block of your config, and that there are no typos.

### Tools appear but calls fail — "API error: ..."

The MCP server started but cannot reach the backend. Check:

1. Is the backend running? `curl http://localhost:8000/health`
2. Is `API_BASE_URL` correct in your config?
3. Is the API key valid? `curl -H "X-API-Key: ak_live_..." http://localhost:8000/api/v1/account/balance`

### No tools appear in Claude Desktop

1. Verify the config JSON is valid — no trailing commas, correct file path
2. Check that `python` resolves to Python 3.12+: `python --version`
3. Check Claude Desktop's MCP server logs panel for error output
4. Run the server manually to see errors: `MCP_API_KEY=ak_live_... python -m src.mcp.server`

### "Connection refused" or timeout errors

The backend is not reachable at `API_BASE_URL`. If running locally:

```bash
# Start the backend
docker compose up -d

# Or without Docker:
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
```

### Debugging with verbose logs

Set `LOG_LEVEL=DEBUG` in your config to see every HTTP request the MCP server makes:

```json
"env": {
  "MCP_API_KEY": "ak_live_...",
  "LOG_LEVEL": "DEBUG"
}
```

Logs go to **stderr** and will not corrupt the MCP protocol stream. In Claude Desktop, they appear in the MCP server logs panel.

---

## Architecture Notes

- **Transport:** stdio (stdin/stdout JSON-RPC) — the MCP standard
- **Authentication:** Every HTTP call includes `X-API-Key` header; optionally `Authorization: Bearer` if `MCP_JWT_TOKEN` is set
- **HTTP client:** `httpx.AsyncClient` with 30-second timeout
- **Stateless:** No state is held in the MCP server — all data lives in the backend
- **No Docker needed:** The MCP server runs on your local machine, not in a container

---

## Further Reading

- [All 58 Tools](/docs/mcp/tools) — complete tool reference with parameters
- [MCP Overview](/docs/mcp/overview) — what MCP is and when to use it
- [Python SDK](/docs/sdk/installation) — for programmatic access in Python agents