MCP Server Setup

Prerequisites

Before setting up the MCP server, you need:

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

docker compose up -d

Verify it is healthy:

curl http://localhost:8000/health

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

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.

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

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

{
  "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"
      }
    }
  }
}

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

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

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

{
  "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.

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

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

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

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:

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:

Is the backend running? curl http://localhost:8000/health
Is API_BASE_URL correct in your config?
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

Verify the config JSON is valid — no trailing commas, correct file path
Check that python resolves to Python 3.12+: python --version
Check Claude Desktop's MCP server logs panel for error output
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:

# 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:

"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