MCP server

Helix Model Context Protocol Server

Point Claude Desktop, Codex, or any MCP client at Helix so the agent can inspect capabilities, generate charts, select plugins, and request PNG, SVG, or JSON outputs in one workflow.

Install the server Create a Helix account

Defensive graph generation

Arbitrary user data still goes through schema checks, chart selection rules, validation, and export cleanup before the response comes back to the agent.

Plugin-aware controls

Agents can guide chart families, export targets, AI controllers, plugin families, and data platforms instead of treating the server like a single opaque chart endpoint.

Discovery for self-configuration

Use get_server_info and list_graph_capabilities so the client can inspect what the server supports before it calls generate_graph.

Set up in Claude Desktop

Install dependencies with python -m pip install -r requirements.txt.
Ensure the Helix account behind ASKFELIX_API_SECRET has an active subscription.
Open Claude Desktop > Settings > Developer > MCP and add a server entry.

{
  "command": "/absolute/path/to/.venv-14/bin/python",
  "args": ["-m", "mcp"],
  "transport": "stdio",
  "env": {
    "ASKFELIX_API_SECRET": "your-secret",
    "ASKFELIX_API_BASE_URL": "https://helixapi.app.nz",
    "ASKFELIX_MCP_DOC_URL": "https://helixapi.app.nz/mcp"
  }
}

Restart Claude and call get_server_info first to confirm the secret resolves to the right account.

Set up in Codex or other MCP CLIs

Add a server entry to ~/.config/codex/mcp.toml and point the command to the interpreter that has the Helix MCP dependencies installed.

[servers.helix]
command = "/absolute/path/to/.venv-14/bin/python"
args = ["-m", "mcp", "--transport", "stdio"]
env.ASKFELIX_API_SECRET = "your-secret"
env.ASKFELIX_API_BASE_URL = "https://helixapi.app.nz"
env.ASKFELIX_MCP_DOC_URL = "https://helixapi.app.nz/mcp"

Run codex mcp test helix before sending chart prompts so transport and auth are verified first.

Make the first graph

Attach or reference a CSV, table, or URL the MCP server can read.
Ask explicitly for a chart plus an output target, for example a PNG preview plus response JSON.
The agent calls generate_graph, selects plugins, and returns the chart plus metadata.

curl -X POST https://helixapi.app.nz/api/mcp/generate_graph \
  -H "Content-Type: application/json" \
  -d '{
        "secret": "your-secret",
        "prompt": "Bar chart of revenue by month; return a PNG image.",
        "output": "png",
        "include_response_json": true
      }'

For local rendering or agent-side post-processing, switch "output" to "json".

Troubleshooting

Authentication: make sure ASKFELIX_API_SECRET belongs to an active account.
Networking: only disable SSL verification for controlled debugging against custom certs.
Timeouts: increase ASKFELIX_API_TIMEOUT for larger datasets or slower warehouses.
Agent debugging: set include_response_json so the raw pipeline payload comes back.

Tools and controls

`generate_graph`

Send a natural-language chart request and receive PNG, SVG, or JSON output.

chart plugin
export target
AI controller
pipeline overrides

`list_graph_capabilities`

Enumerate plugins and export targets before the agent commits to a graph request.

chart families
export families
data platform filters

`get_server_info`

Return base URL, default output, timeout, and documentation hints for client self-configuration.

read-only discovery
health check entry point
doc link exposure

Inputs are Pydantic-validated so agents get fine-grained control without sending unbounded or malformed payloads.