Environment:HKUDS AI Trader MCP Services

Knowledge Sources	AI-Trader MCP Protocol FastMCP
Domains	Infrastructure, MCP
Last Updated	2026-02-09 14:00 GMT

Overview

Local MCP (Model Context Protocol) service runtime providing Math, Search, Trade, Price, and CryptoTrade tool servers on configurable HTTP ports for LangChain agent tool binding.

Description

The AI-Trader system runs five MCP tool servers as local subprocesses, each exposing a Streamable HTTP endpoint. These services provide the agent with concrete tools: arithmetic operations (Math), news/web search (Search via Alpha Vantage News), stock trading simulation (Trade), local price data lookup (Price), and cryptocurrency trading simulation (CryptoTrade). The MCPServiceManager orchestrates launching, health-checking, and shutting down all services.

Usage

Must be started before any agent trading session. The MCPServiceManager.start_all_services() method launches all services, or they can be started individually. The agent's initialize() method connects to these services via MultiServerMCPClient.

System Requirements

Category	Requirement	Notes
Ports	5 available localhost ports	Default: 8000, 8001, 8002, 8003, 8005
Process	Subprocess spawning	Uses Python subprocess module
Signals	POSIX signal handling	SIGINT/SIGTERM for graceful shutdown

Dependencies

Python Packages

fastmcp == 2.12.5 (MCP server framework)
langchain-mcp-adapters >= 0.1.0 (MCP client for LangChain)

Service Port Mapping

Service	Default Port	Env Variable	Script
Math	8000	`MATH_HTTP_PORT`	`agent_tools/tool_math.py`
Search (News)	8001	`SEARCH_HTTP_PORT`	`agent_tools/tool_alphavantage_news.py`
Trade (Stocks)	8002	`TRADE_HTTP_PORT`	`agent_tools/tool_trade.py`
Price (Local)	8003	`GETPRICE_HTTP_PORT`	`agent_tools/tool_get_price_local.py`
CryptoTrade	8005	`CRYPTO_HTTP_PORT`	`agent_tools/tool_crypto_trade.py`

Credentials

MCP services themselves do not require credentials, but the services they wrap may:

Search service: Requires ALPHAADVANTAGE_API_KEY for news fetching
Price service: Reads local JSON files (no API key needed)
Trade/CryptoTrade: Read/write local position files (no API key needed)

Quick Install

# Start all MCP services (blocking, runs in foreground)
python agent_tools/start_mcp_services.py

# Or configure custom ports via environment
MATH_HTTP_PORT=9000 SEARCH_HTTP_PORT=9001 python agent_tools/start_mcp_services.py

Code Evidence

Service startup and port checking from agent_tools/start_mcp_services.py:20-43:

class MCPServiceManager:
    def __init__(self):
        self.services = {}
        self.running = True
        self.ports = {
            "math": int(os.getenv("MATH_HTTP_PORT", "8000")),
            "search": int(os.getenv("SEARCH_HTTP_PORT", "8001")),
            "trade": int(os.getenv("TRADE_HTTP_PORT", "8002")),
            "price": int(os.getenv("GETPRICE_HTTP_PORT", "8003")),
            "crypto": int(os.getenv("CRYPTO_HTTP_PORT", "8005")),
        }

Agent MCP client connection from agent/base_agent/base_agent.py:309-328:

def _get_default_mcp_config(self) -> Dict[str, Dict[str, Any]]:
    return {
        "math": {
            "transport": "streamable_http",
            "url": f"http://localhost:{os.getenv('MATH_HTTP_PORT', '8000')}/mcp",
        },
        "stock_local": {
            "transport": "streamable_http",
            "url": f"http://localhost:{os.getenv('GETPRICE_HTTP_PORT', '8003')}/mcp",
        },
        # ... additional services
    }

MCP initialization failure handling from agent/base_agent/base_agent.py:372-377:

except Exception as e:
    raise RuntimeError(
        f"Failed to initialize MCP client: {e}\n"
        f"   Please ensure MCP services are running at the configured ports.\n"
        f"   Run: python agent_tools/start_mcp_services.py"
    )

Common Errors

Error Message	Cause	Solution
`Failed to initialize MCP client`	MCP services not running	Run `python agent_tools/start_mcp_services.py` first
`Warning: No MCP tools loaded`	Services started but not responding	Check port availability and service logs in `logs/`
`Address already in use`	Port conflict	Change ports via env variables or stop conflicting processes

Compatibility Notes

Port 8004 gap: The default port sequence skips 8004 (Search uses 8001, not 8004 as sometimes referenced). The agent's MCP config uses port 8004 for search, but the service manager starts it on 8001. Ensure consistency.
Graceful shutdown: SIGINT/SIGTERM handlers are installed for clean subprocess termination.
Log directory: Service logs are written to logs/ relative to the service manager.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment