MCP Server (self-hosted)¶
TradeServer includes a built-in Model Context Protocol (MCP) server that exposes its full trading API as structured tools consumable by AI agents and large language models (LLMs).
This allows you to connect any MCP-compatible AI client — such as Claude, Codex, Cursor, or a custom agent — directly to your TradeServer instance and automate tasks using natural language or programmatic tool calls.
Two ways to connect
This page covers the self-hosted setup. Your agent connects with an API key you create in your own instance or, where the AI Agent page offers it, with the same one-click browser authorization HaasOnline TradeServer Cloud uses, which needs no API key. See AI Agent Access (MCP) under TradeServer Cloud.
What is MCP?¶
Model Context Protocol is an open standard for connecting AI systems to external data sources and tools. Instead of building custom integrations for each AI client, TradeServer exposes a single MCP endpoint that any compliant client can discover and call.
With MCP, an AI agent can:
- List and manage your trading bots
- Create, edit, and compile HaasScripts
- Run backtests and retrieve results
- Execute and monitor Labs (parameter optimization)
- Query wallet balances and portfolio values
- Check market data availability
Endpoints¶
The MCP server is hosted on the same REST server as the regular TradeServer API.
| Endpoint | Method | Description |
|---|---|---|
/mcp |
POST |
JSON-RPC 2.0 endpoint — spec-compliant MCP interface |
/mcp/tools |
GET |
Returns a human-readable list of all available tools |
/mcp/execute |
POST |
Simplified execute endpoint — accepts {"name": "...", "args": {...}} |
JSON-RPC 2.0 example¶
POST /mcp
Content-Type: application/json
Authorization: Bearer <your-api-key>
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_bots",
"arguments": {}
}
}
Direct execute example¶
POST /mcp/execute
Content-Type: application/json
Authorization: Bearer <your-api-key>
{
"name": "get_bot",
"args": {
"botid": "abc123"
}
}
Setup¶
1. Open the AI Agent page¶
In the TradeServer interface, open AI Agent → Connect an agent in the left menu. The Connect with an API key section on this page is the setup for self-hosted TradeServer. What you see depends on your server:
- Your server advertises OAuth discovery: the page also offers one-click setup at the top, which needs no API key. Use the commands shown there, which point at your own server; the flow is the one described under Setup in the Cloud guide, including what happens when you approve. The API-key setup below is folded under Show legacy API-key setup (deprecated). Click it to use an API key anyway; existing API-key connections keep working.
- Your server does not advertise OAuth discovery: the page says so, and the API-key setup is shown open. Follow the steps below.
Settings → MCP no longer holds the setup. It lists your connected agents so you can disconnect them.
2. Create an API Key¶
Open Menu (top right) → Settings → API Keys and click the + button to create a new key. Give it a descriptive name (e.g. Claude Desktop) so you can identify it later. On self-hosted TradeServer every API key has full access; there are no per-key permissions.
Copy the key when it is shown, as it will not be shown again.
Warning
Keep your API key secret. Anyone with the key has full access to your bots, scripts, and exchange accounts via the MCP interface.
3. Connect Your AI Client¶
The Connect with an API key section on the AI Agent page includes ready-to-use config snippets for Claude Desktop, Claude Code, Codex, Cursor, Windsurf, Antigravity, Zed, and others. Select your client from the tabs, copy the snippet shown, paste your API key into it, and add it to your terminal or client config file. Restart your agent afterward.
Info
If TradeServer is not running on the same machine as your AI client, replace 127.0.0.1:8080 in the snippet with your server's hostname or IP address and the configured port.
Authentication¶
Every MCP request carries a Bearer token in the Authorization header. With the API-key setup, that token is your API key:
With one-click setup, your agent obtains and refreshes its own access token through the browser authorization, so there is no key to paste.
Protocol Details¶
| Property | Value |
|---|---|
| Protocol version | 2025-11-25 |
| Server name | HaasOnline Trade Server |
| Server version | 1.0.0 |
| Transport | HTTP (JSON-RPC 2.0) |
Treat what your agent reads as untrusted
Your agent reads text you did not necessarily write — script source, bot names, logs — and anyone who can get text in front of it can attempt to plant instructions for it to follow. Leave tool confirmation enabled in your client, and read what it proposes before approving, particularly anything that deletes or overwrites. See Treat what your agent reads as untrusted — the guidance is the same for both deployments.
Available Tools¶
The MCP server exposes 47 tools across eight functional areas:
| Category | Tools |
|---|---|
| System | 1 |
| HaasScript Management | 7 |
| Backtest Execution | 12 |
| Trading Bots | 8 |
| Exchange Accounts | 2 |
| Labs (Parameter Optimization) | 10 |
| Markets & Price Data | 3 |
| Wallet & Portfolio | 4 |
See the Tools Reference for the complete list with parameters and descriptions.