Spera Agent Plugin

Build, backtest, and document algorithmic trading strategies from your coding agent. Spera packages its production MCP server and eight portable Agent Skills as an Agent Plugin, with compatibility adapters for Claude Code, Cursor, and ChatGPT/Codex. The same skills and the same MCP server back every client, so a workflow you learn in one carries over to the next.

Install

Claude Code

/plugin marketplace add praveenmanikandan/spera-cursor-plugin
/plugin install spera@spera

If the install summary says Run /reload-plugins to activate., run that. Then authenticate:

/mcp

Select spera, choose Authenticate, and approve the scopes on Spera's consent screen. Verify with /spera:spera-foundations or by asking Claude to call spera_context_get — a complete grant reports contract 1.0, 10 scopes, and 42 tools.

Skills are namespaced by the plugin, so they invoke as /spera:spera-build-strategy, /spera:spera-run-backtest, and so on. The names match the Cursor and Codex packages deliberately: a workflow you know in one client is the same workflow here.

Cursor

Install Spera from Cursor Directory, or copy or link this repository into Cursor's local plugin directory:

~/.cursor/plugins/local/spera

Restart Cursor or run Developer: Reload Window, then open Customize and confirm Spera's skills and MCP server are listed. Until you sign in, the spera server reports that it needs authentication: choose Authenticate, approve the scopes on Spera's consent screen, then restart Cursor so the new grant attaches. If the server shows Error with no Authenticate option, run node scripts/doctor.mjs from this repository and check the sign-in trigger line.

ChatGPT / Codex

The repository root contains .codex-plugin/plugin.json, the Codex .app.json mapping to Spera's registered OpenAI app, the eight portable skills, and transparent 512×512 PNG marketplace assets. Point a local Codex marketplace entry at this repository, install spera from it, and start a new task.

Other Agent Plugins clients

plugin.json and mcp.json at the repository root are vendor-neutral Agent Plugins 1.0.0 manifests. Install through whatever workflow your client supports; clients own their installation UI and OAuth token storage.

What you get

Eight skills that teach the agent the correct order of operations, the recovery paths, and the stopping rules — not just the tool schemas:

Skill	What it does
`spera-foundations`	Connect, inspect authorized projects, resume durable workflows, enforce revision/receipt rules
`spera-build-strategy`	Create, edit, fork, repair, and compile strategy graphs
`spera-build-module`	Build reusable graph modules and publish their ports
`spera-build-custom-node`	Author, compile, and repair Rust/Wasm custom nodes
`spera-run-backtest`	Quick and durable deep backtests against an exact revision
`spera-update-project-knowledge`	Revision-safe project Markdown, with protected `STRATEGY.md` proposals
`spera-write-documentation`	Receipt-grounded artifact documentation
`spera-deliver-strategy`	Compose the above into a documented, backtested handoff

A complete authoring grant exposes 42 MCP tools.

Context cost: roughly 865 tokens of always-on context across the eight skills; each skill costs more only when it actually fires. Claude Code shows this in the plugin details view before you install.

Scopes it requests

spera:context:read, spera:artifact:read, spera:artifact:write, spera:backtest:run, spera:backtest:read, spera:backtest:cancel, spera:knowledge:read, spera:knowledge:write, spera:documentation:read, spera:documentation:write.

Approve only what the consent screen shows. Adding scopes later requires you to reauthorize.

What it deliberately cannot do

There is no tool at any scope that can:

create, start, stop, pause, or deploy a paper or live trading bot
operate Fleet
read or use exchange API credentials
place, modify, or cancel a real order

Bots are started by a person in the Spera app. A compile receipt proves a strategy is structurally valid; a backtest receipt is historical evidence for one exact revision under one exact configuration. Neither is a performance promise, and neither authorizes deployment.

Connection

The plugin connects to https://api.spera.bot/mcp?mode=authoring over Streamable HTTP. The ?mode=authoring suffix is what makes the server request the ten authoring scopes; the equivalent X-Spera-MCP-Mode: authoring header is sent alongside for clients that forward custom headers, but many connector interfaces drop them, and a grant obtained against the bare URL is read-only.

The header also decides how a tokenless initialize is answered. A request that carries it — every native plugin config in this repository — gets 401 with the OAuth challenge, which is what makes Cursor offer Authenticate. A request by URL alone (ChatGPT connectors, tool scanners) gets anonymous discovery instead. Keep the header in every mcp.json. This repository contains no access token, client secret, or exchange credential — OAuth is run by your client and the resulting authorization is stored by your client.

Trust and updates

Claude Code shows a trust warning when you add any third-party marketplace: Anthropic does not verify third-party plugins. This repository is the full source of what gets installed — the manifests, the MCP endpoint, and all eight skill files are readable above.

Third-party marketplaces have auto-update off by default. To pick up new versions, either enable auto-update for the spera marketplace in /plugin → Marketplaces, or refresh manually:

/plugin marketplace update spera

Repository layout

plugin.json, mcp.json — vendor-neutral Agent Plugins 1.0.0 manifests
skills/ — the eight portable Agent Skills, shared by every client
.claude-plugin/ — Claude Code manifest, MCP server file, and single-plugin marketplace
.cursor-plugin/plugin.json — Cursor listing metadata
.codex-plugin/plugin.json, .app.json — Codex packaging and registered app mapping
commands/, scripts/doctor.mjs — /spera-connect, /spera-doctor, and the connection doctor

The portable manifests, the Claude adapter, the skills, the commands, and the doctor are generated from one canonical profile in the Spera repository, so the clients cannot drift apart. The Cursor and Codex manifests, .app.json, and this README are maintained here and checked against the generated files by npm test.

Repository checks

Node.js 20 or newer, no third-party dependencies:

npm test
npm run test:live
npm run validate:submission
node scripts/doctor.mjs

npm test validates every manifest, the MCP profiles, the portable skills, documentation, secret hygiene, and the Codex PNG dimensions and transparency. test:live exercises the public MCP OAuth discovery chain. validate:submission additionally requires an approved open-source license. scripts/doctor.mjs probes the live server without a token: anonymous discovery, the sign-in trigger, the scope challenge, and OAuth discovery.

Claude Code users can also run its own validator against a clone:

claude plugin validate .

Data handling, privacy, and support

Data handling: DATA_HANDLING.md
Security policy: SECURITY.md
Privacy policy: https://www.spera.bot/privacy
Terms of service: https://www.spera.bot/terms
Support and bug reports: support@spera.bot, or open an issue on this repository

Never include access tokens, exchange credentials, or private keys in prompts, issues, or support requests.