Hermes-Skills/longbridge-cli/references/longport-mcp-integration.md

LongPort MCP Integration

LongPort offers an MCP (Model Context Protocol) server as an alternative to the longbridge CLI and Python SDK. This is useful for AI agents that need native MCP tool discovery rather than custom CLI/SDK integration.

Architecture

LongPort's MCP service uses a two-endpoint architecture:

Endpoint	URL	Purpose
Auth endpoint	https://mcp.longport.cn/agent	Single tool: authenticate — exchanges an auth code for an access token
Main service	https://mcp.longport.cn	All LongPort data tools (quotes, orders, positions, etc.) — requires Bearer token

The auth endpoint exists only for credential exchange and is NOT a permanent MCP service; disconnect it after obtaining the token.

Auth Flow (Two Steps)

Step 1: Get Access Token

Connect to https://mcp.longport.cn/agent and call the authenticate tool:

POST https://mcp.longport.cn/agent
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "authenticate",
    "arguments": {
      "code": "<one-time auth code from LongPort App>"
    }
  },
  "id": 1
}

Response includes the access token and the exact config command for the main service (e.g., headers with Authorization: Bearer <token>).

Auth codes: Single-use, valid for ~10 minutes. Generate from LongPort App → Open API → MCP.

Step 2: Connect Main Service

Once you have the token, connect to the main MCP service with the Bearer token as a request header:

# In Hermes config.yaml under mcp_servers:
mcp_servers:
  longport:
    url: "https://mcp.longport.cn"
    headers:
      Authorization: "Bearer <your_access_token>"
    timeout: 180
    connect_timeout: 60

After adding the config, restart Hermes Agent. All LongPort MCP tools will auto-discover and become available as mcp_longport_* tools.

The temp auth endpoint (/agent) connection can be removed after token exchange — it's not needed for regular use.

Tool Availability

Once connected to the main service, available tools include:

• Quote tools: real-time quotes, candlesticks, calc_indexes
• Account tools: positions, balance, orders
• Trade tools: buy, sell, cancel orders
• Watchlist tools: list groups, securities
• Static info: EPS, BPS, shares outstanding

(The tool names auto-prefix as mcp_longport_<tool_name> in Hermes.)

Token Management

• Expiry: LongPort access tokens expire after ~180 days (same as API tokens).
• Refresh: Generate a new auth code from the LongPort App and repeat the two-step flow.
• 401003: Token expired — re-authenticate from scratch.
• 401004: Token invalid/truncated — verify the token JWT structure is intact.

Troubleshooting

DNS / Connectivity

The LongPort MCP servers live at mcp.longport.cn. If this domain doesn't resolve:

dig mcp.longport.cn
curl -s -o /dev/null -w "%{http_code}" https://mcp.longport.cn

• China mainland access: DNS may be blocked or restricted. Try a VPN/WireGuard exit to Hong Kong or overseas. Use the WireGuard on/off scripts (wg-on, wg-off) if available.
• Timeout: Increase connect_timeout to 60–120s. LongPort MCP can be slow to respond on first connection.
• ERR_NAME_NOT_RESOLVED: Domain unreachable from current network. Try alternate DNS (8.8.8.8) or VPN.

Auth Code Expiry

Auth codes are single-use and expire ~10 minutes after generation. If you get an error calling authenticate:

• Generate a fresh code from the LongPort App
• Retry step 1 immediately

MCP SDK Requirement

Hermes' native MCP client requires the mcp Python package:

pip install mcp
# or
uv pip install mcp

Without it, MCP support is silently disabled and no MCP servers connect.

See Also

• native-mcp skill: general MCP client configuration for Hermes
• longbridge-cli skill: CLI-based LongPort access (fallback if MCP is unavailable)
• longbridge-python-sdk skill: Python SDK-based LongPort access