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

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

```bash
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:

```bash
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
