# VMCP Agent Integration Guide

Use this file to help coding agents and AI clients connect to VMCP.

## Service URLs

Use the public VMCP service address for new integrations:

```text
Service base URL: https://vmcp.hzinsights.com
MCP endpoint: https://vmcp.hzinsights.com/mcp/
HTTP API base URL: https://vmcp.hzinsights.com/api/v1
```

The previous endpoint remains valid for compatibility with existing clients:

```text
Compatibility MCP endpoint: https://vmcp.internal.hzinsights.com/mcp/
Compatibility API base URL: https://vmcp.internal.hzinsights.com/api/v1
```

## Preferred Transport

Prefer MCP first. Use the MCP endpoint when the client supports Streamable HTTP MCP:

```text
MCP endpoint: https://vmcp.hzinsights.com/mcp/
Authorization: Bearer <USER_TOKEN>
```

VMCP supports two authorization modes:

- Pre-issued Bearer tokens from the VMCP user center.
- OAuth authorization-code + PKCE for AI web app connectors.

OAuth discovery endpoints:

- Authorization server metadata: https://vmcp.hzinsights.com/server/.well-known/oauth-authorization-server
- MCP protected resource metadata: https://vmcp.hzinsights.com/server/.well-known/oauth-protected-resource/mcp
- Dynamic client registration: https://vmcp.hzinsights.com/server/oauth/register

Do not use client-credentials machine authorization; VMCP connector OAuth is user-delegated.

Recommended MCP flow:

1. Create or copy a token from the VMCP user center.
2. Configure the MCP client with `https://vmcp.hzinsights.com/mcp/`.
3. Send the token as `Authorization: Bearer <USER_TOKEN>` or the client's equivalent `auth` field.
4. Call `tools/list` to discover available tools.
5. Call `tools/call` with the selected tool name and JSON arguments.

MCP result payload:

- For structured VMCP tools, `content[].text` contains the complete JSON result, including `message`, `data`, result-set columns, rows, dtypes, and metadata.
- The same object is also available as `structuredContent` for MCP clients that expose structured tool results.
- If an agent runtime only forwards `content` into the LLM context, use the JSON text from `content[].text`; do not rely only on the human-readable `message`.

FastMCP Python example:

```python
from fastmcp import Client

async with Client("https://vmcp.hzinsights.com/mcp/", auth="<USER_TOKEN>") as client:
    tools = await client.list_tools()
    result = await client.call_tool("search_code", {"keyword": "平安"})
```

## API Fallback

If MCP is unavailable in the current agent runtime, fall back to the HTTP API.

List tools:

```bash
curl https://vmcp.hzinsights.com/api/v1/tools \
  -H "Authorization: Bearer <USER_TOKEN>"
```

Call a tool through the generic API:

```bash
curl -X POST https://vmcp.hzinsights.com/api/v1/tools/get_data/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <USER_TOKEN>" \
  -d '{"arguments":{"query":"帮我看看茅台最近的行情和估值"}}'
```

Call a tool through its direct API path:

```bash
curl -X POST https://vmcp.hzinsights.com/api/v1/get_data \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <USER_TOKEN>" \
  -d '{"query":"帮我看看茅台最近的行情和估值"}'
```

## Tool Selection Hints

- Use `search_code` before querying a specific security when the code is unknown.
- Use `get_basicinfo` when an A股 `TRADE_CODE` is known and you need company profile, industry, business scope, listing date, or shareholder fields.
- Use `search_chart` to find chart IDs. Then call `get_chart_settings` to inspect `chart_settings`: rendering parameter definitions, not chart data. Use the returned `chart_settings.varname` keys in `get_chart_data.selection_values` to fetch data for specific selections.
- Use `search_news` for current finance news search. The server fixes the search topic to finance; do not pass a topic argument.
- Use `get_data` for broad natural-language financial data questions.
- Use specialized tools when the requested task exactly matches a listed schema from `/api/v1/tools`.
- Keep each request narrow. Large date ranges or broad universes consume more credits and may hit service result limits.
- When a query returns too much data, narrow by date range, market, ticker, industry, or metric.

## Credits

Successful calls consume credits according to returned data volume:

```text
credits = max(1, ceil(result_rows / 100), ceil(result_bytes / 50KB))
```

Failed authentication, validation errors, and failed tool calls do not consume credits. Usage details are visible in the user center.

## Error Handling

- `401`: token missing, invalid, or expired.
- `402`: credits are insufficient. Reduce query size or buy a plan.
- `403`: no active subscription or account disabled.
- `429`: rate limit exceeded. Retry later with backoff.
- `5xx`: service or upstream data error. Retry later or switch to a narrower query.