pyon-mcp

MCP (Model Context Protocol) server for the Pyon trading platform. It lets AI agents - Claude Code, Claude Desktop, Codex, or any MCP client - drive Pyon end to end: search markets, generate research, build and edit node-graph strategies with AI, run backtests, diagnose problems, and optimize parameters with 2-D sweeps.

Runs over stdio, talks to api.pyon.io, and needs only Node 18+.

Getting an API key

1. Sign in at app.pyon.io.
2. Open Account > API Access.
3. Create a personal access token. It looks like pyk_....

Set it as the PYON_API_KEY environment variable wherever the server runs.

Variable	Required	Default	Purpose
PYON_API_KEY	yes	-	Personal access token (pyk_...)
PYON_API_URL	no	https://api.pyon.io	API base URL override

Setup

Claude Code

claude mcp add pyon -e PYON_API_KEY=pyk_... -- npx -y pyon-mcp

Or, from a local checkout:

npm install && npm run build
claude mcp add pyon -e PYON_API_KEY=pyk_... -- node /path/to/pyon-mcp/dist/index.js

Claude Desktop

Add to claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "pyon": {
      "command": "npx",
      "args": ["-y", "pyon-mcp"],
      "env": {
        "PYON_API_KEY": "pyk_..."
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.pyon]
command = "npx"
args = ["-y", "pyon-mcp"]
env = { PYON_API_KEY = "pyk_..." }

Start here: get_capabilities

Pyon turns a strategy description into a node graph literally. An indicator name the engine does not know, or a threshold outside an indicator's range, produces a strategy that backtests to zero trades and looks broken for no visible reason - an RSI > 120 entry can never fire, because RSI is bounded 0-100.

So call get_capabilities before writing any strategy description, edit instruction, or sweep bound. It returns the real catalog: 61 market indicators with their value ranges and indicatorParams, 9 portfolio indicators, 8 operators, 8 trigger types, 13 action types, the 5 supported timeframes, the 3 quantityType modes, 7 option strategyType values, and the 47 tradable tickers.

The catalog is fetched from GET /api/capabilities and falls back to a copy bundled with this server if that endpoint is unavailable. Every response names which source it used. The same catalog is readable as markdown in the pyon://capabilities resource.

Tools

Every input schema is strict: an unknown or misspelled parameter (timeFrame, start_date, limit) is rejected with an explicit error rather than silently ignored. Every rejection message states what IS allowed.

Tool	Parameter	Type	Allowed values	Default
get_capabilities	section	enum, optional	indicators, portfolio_indicators, operators, triggers, actions, timeframes, tickers, all	all
search_symbols	query	string, required	1-100 chars; ticker or name fragment	-
list_strategies	-	-	no parameters	-
get_strategy	strategyId	string, required	UUID from list_strategies or create_strategy	-
create_strategy	description	string, required	at least 10 chars after trimming, max 8000	-
	analysisId	string, optional	UUID from create_research or list_research	none
edit_strategy	strategyId	string, required	UUID	-
	instruction	string, required	at least 10 chars after trimming, max 8000	-
run_backtest	strategyId	string, required	UUID	-
	startDate	string, optional	YYYY-MM-DD, real calendar date, not in the future	365 days ago
	endDate	string, optional	YYYY-MM-DD, not in the future, after startDate, at least 7 days from it	today
	timeframe	enum, optional	1m, 5m, 15m, 1h, 1d (lowercase)	the strategy's native timeframe
	initialCapital	number, optional	100 to 100000000	50000
diagnose_strategy	strategyId	string, required	UUID	-
	question	string, optional	at least 10 chars when given, max 2000	general health check
optimize_strategy	strategyId	string, required	UUID	-
	xNodeId	string, required	a node id from get_strategy	-
	xField	string, required	a numeric config key on that node	-
	xMin / xMax	number, required	finite; xMax strictly greater than xMin	-
	yNodeId	string, required	a node id from get_strategy; may equal xNodeId	-
	yField	string, required	a numeric config key; the two axes must not be the same node and field	-
	yMin / yMax	number, required	finite; yMax strictly greater than yMin	-
	steps	integer, optional	3 to 10 (runs steps x steps backtests)	5
	timeframe	enum, optional	1m, 5m, 15m, 1h, 1d	server's choice
create_research	prompt	string, required	at least 10 chars after trimming, max 8000	-
get_research	analysisId	string, required	UUID from create_research or list_research	-
list_research	-	-	no parameters	-
get_job_status	jobId	string, required	non-empty; a job id or a backtest id from a timeout message	-

What each tool does

Tool	Summary	Wait
get_capabilities	The indicator / operator / action / ticker catalog, with API fetch and bundled fallback	none
search_symbols	Resolve tickers and names against Pyon's market database	none
list_strategies	Saved strategies with id, name, nodeCount, updatedAt	none
get_strategy	Per-node id, type, label, and flattened config (feeds optimize_strategy)	none
create_strategy	AI-build a new strategy, optionally grounded in research	up to 300s
edit_strategy	AI-edit a strategy; returns a before/after verification verdict	up to 300s
run_backtest	Metrics plus verbatim diagnostics; flags 0-trade causes and short daily windows	up to 180s
diagnose_strategy	AI debugger with sample-backtest evidence; message, issues, suggested fix	up to 300s
optimize_strategy	2-D parameter sweep; best cell, current cell, sharpe grid	up to 600s
create_research	Generate a saved research report; returns analysisId plus executive summary	up to 300s
get_research	Fetch a saved report: score, view, truncated narratives	none
list_research	List saved research reports	none
get_job_status	Escape hatch when a wait timed out; also accepts backtest ids	none

Validation rules worth knowing

• Ids are UUIDs. A strategy name will be rejected; the message points at list_strategies.
• Dates are YYYY-MM-DD real calendar dates, never in the future. 2025-02-30, 2024-1-5, 01/02/2024 and full timestamps are all rejected.
• Backtest windows need endDate after startDate and at least 7 days between them. A 1d strategy tested over fewer than 300 days still runs, but the result carries a warning explaining that the window, not the strategy, may be what the metrics are measuring.
• Timeframes are exactly 1m, 5m, 15m, 1h, 1d. 1D, daily, 1w and 30m are rejected - these are the five bar sizes the engine resolves.
• Sweep axes must describe a real range (xMax > xMin, yMax > yMin) and must not point at the same node id and config field, which would test one dimension twice.
• Prompts for create_strategy, edit_strategy, create_research and the optional diagnose_strategy question need at least 10 characters, because a vague prompt produces a vague strategy.

Resources

URI	Contents
pyon://getting-started	Auth setup, the typical agent workflow, enforced input rules, plan limits
pyon://capabilities	The full capability catalog as readable markdown

Errors you may see

• 401 - invalid or revoked API key. Create a new one in Account > API Access at app.pyon.io.
• 402 - a plan limit was hit; the message explains which. Upgrade at app.pyon.io/app/account/billing.
• Timeouts - long AI jobs keep running server-side; the timeout message includes the job id to check with get_job_status.
• Invalid arguments - the message names the parameter and the allowed values. Fix and retry; these never reach the API.

Development

npm install
npm run build   # tsc -> dist/
npm run smoke   # offline, keyless: tools/list, JSON Schema completeness, and the validation tables
npm run check   # build + smoke

The compiler runs at the strictest settings the code satisfies: strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, verbatimModuleSyntax, isolatedModules, noImplicitOverride, noImplicitReturns, noFallthroughCasesInSwitch, noUnusedLocals, noUnusedParameters, allowUnreachableCode: false and allowUnusedLabels: false. noPropertyAccessFromIndexSignature is deliberately left off: it only forces process.env["PYON_API_KEY"] bracket syntax and catches nothing here. Wire payloads are read through the case-insensitive helpers in src/format.ts, which return unknown, so every tool has to narrow a value before putting it in one of the interfaces in src/types.ts - a backend field rename surfaces as a compile error rather than a missing JSON key.

scripts/smoke.mjs runs entirely offline. It asserts the 13 tools and 2 resources are registered, that every published JSON Schema names its parameters and sets additionalProperties: false, and it drives every tool's zod schema with a table of bad inputs that must be rejected and good inputs that must parse. It exits non-zero on any failure.