sequenx-mcp (SequenxAI MCP server)

MCP server that exposes the SequenxAI public API as tools for AI hosts (Claude Desktop, Cursor, …). It is a thin adapter: every tool maps one-to-one onto an existing operation and calls the Python SDK — there is no second HTTP client and no business logic here (see docs/plans/phase_3/06-MCP服务器与宿主Agent工具面.md).

Not published on PyPI yet; it lives in this repository.

Install

The server depends on the sibling SDK, which is not on PyPI either — install it from this repository first:

pip install -e packages/sequenx-py
pip install -e packages/sequenx-mcp

Run

The server speaks stdio, the transport a local MCP host starts as a child process:

SEQUENX_API_KEY=sqx_live_... python -m sequenx_mcp

Host configuration (any MCP host that starts stdio servers):

{
  "mcpServers": {
    "sequenx": {
      "command": "python",
      "args": ["-m", "sequenx_mcp"],
      "env": { "SEQUENX_API_KEY": "sqx_live_..." }
    }
  }
}

Tools

Input rows are the contract's long table: unique_id, ds, y.

Limits. forecast takes inline rows only — the public API has no dataset upload, so the tool is for small-to-medium series. The model reads only the most recent points of a series: a longer history is truncated by the API and reported (model_input[].truncated plus a context_truncated warning), and list_models gives each model's context window. The server adds no limit of its own. For larger data use the REST or SDK batch path: POST /v1/forecast/batch, then poll GET /v1/forecast/batch/{job_id}.

Errors. A tool error carries the contract's error body ({"error": {code, message, request_id, category, retryable, details?}}), so the host agent sees a structured error instead of a silent empty answer. The MCP framework prefixes the message with its own text, so the envelope travels inside the error text. 403 is not retried; 429 carries retry_after and limit_type (rpm / daily) in details.

Three codes are the SDK's own, because the contract's code list covers server-side failures only: HTTP_<status> (a response without a code), REQUEST_FAILED (a response body the SDK could not read) and TRANSPORT_ERROR (the request never reached the server).

Development

pip install -e packages/sequenx-py
pip install -e packages/sequenx-mcp -r packages/sequenx-mcp/requirements-dev.txt
cd packages/sequenx-mcp
python -m pytest -q
python -m ruff check src tests

Gitee Go runs the suite via scripts/ci/gitee-verify.sh mcp.

Use a separate virtualenv for this package: mcp 2.x installs httpx2, and a control-plane environment that has httpx2 next to httpx breaks Starlette's test client (services/api needs httpx 1.x).