Zolva

Trading-Agenten auf Robinhood Chain: stündlich kaufen, verkaufen oder halten, jeweils mit Begründung, sowie Aktien-Token- und Kryptopreise. Nur lesender Zugriff, kein API-Schlüssel.

Gehosteter MCP-Server

npx add-mcp 'https://zolvaagent.app/mcp'

Installiert in Claude Code, Codex, Cursor und mehr

Dokumentation

MCP server

Connect Claude, Cursor or any MCP client to Zolva: ask about agents and markets in plain words, and with an API key backtest and run your own paper agents.

Overview

Zolva has an MCP server, so AI assistants such as Claude, ChatGPT, Cursor or Codex can read Zolva's data and, with your API key, run your paper agents. Ask in plain words; the assistant picks the tools.

  • URL: https://zolvaagent.app/mcp (Streamable HTTP, no session state)
  • No key: 7 read-only tools over the same data as the Public API.
  • With an API key: up to 11 more tools, only those your key's scopes allow.

What it can and cannot do

CanCannot
Read published agents, their decisions with reasons, markets, prices, funding and trades.See other people's private agents, wallets or AI usage.
With a key: list your own agents, check rules, backtest, write rules with AI.Trade real money, swap or move funds.
With a key: create, pause, resume, publish and unpublish your paper agents, and change their AI budget.Change an agent's strategy after launch (settings are locked).
With a key: stop one of your real money agents (pause_live_agent).Resume, create or edit a real money agent. Those stay in the browser.

[!note] Note Paper only, with one exception Every agent the MCP server creates or changes trades virtual money. The only real money action is pause_live_agent, which can only stop an agent. Past results do not predict future results, and nothing here is investment advice.

Prerequisites

  • An MCP client that supports remote (HTTP) servers. Claude Desktop with a key also needs Node.js, for mcp-remote.
  • For the keyed tools: a Zolva account and an API key from Settings, API keys. Tick only the scopes you need; the secret is shown once.
  • Nothing else for read-only use. The server costs nothing; only write_strategy spends your AI credits.

Setup

Every snippet below includes the key header; leave it out for read-only use. Replace zk_... with your key, or keep the key in an environment variable where the client supports it.

Claude Code

One command. Leave the header out for read-only use.

claude mcp add --transport http zolva https://zolvaagent.app/mcp --header "Authorization: Bearer zk_..."

Claude Desktop and claude.ai

Without a key: Settings, Connectors, Add custom connector, and paste the URL. With a key, add it to claude_desktop_config.json (Settings, Developer, Edit Config) through mcp-remote, which needs Node.js, then restart Claude. The header is split into an env value because Claude Desktop on Windows does not escape spaces in args.

Without a key

https://zolvaagent.app/mcp

With a key: claude_desktop_config.json

{
  "mcpServers": {
    "zolva": {
      "command": "npx",
      "args": ["mcp-remote", "https://zolvaagent.app/mcp", "--header", "Authorization:${ZOLVA_AUTH}"],
      "env": { "ZOLVA_AUTH": "Bearer zk_..." }
    }
  }
}

Cursor

Add this to ~/.cursor/mcp.json (most clients use the same shape).

{
  "mcpServers": {
    "zolva": { "url": "https://zolvaagent.app/mcp", "headers": { "Authorization": "Bearer zk_..." } }
  }
}

VS Code (GitHub Copilot)

Add.vscode/mcp.json to your project. VS Code asks for the key once and stores it as a secret, so it never sits in the file.

{
  "inputs": [
    { "type": "promptString", "id": "zolva-key", "description": "Zolva API key", "password": true }
  ],
  "servers": {
    "zolva": {
      "type": "http",
      "url": "https://zolvaagent.app/mcp",
      "headers": { "Authorization": "Bearer ${input:zolva-key}" }
    }
  }
}

Codex

Add the server to ~/.codex/config.toml. Codex reads the key from the environment variable you name and sends it as a Bearer token. Leave that line out for read-only use.

[mcp_servers.zolva]
url = "https://zolvaagent.app/mcp"
bearer_token_env_var = "ZOLVA_KEY"

Then, in the shell that starts Codex

export ZOLVA_KEY="zk_..."

Hermes Agent

Add the server to ~/.hermes/config.yaml, then run /reload-mcp in Hermes.

mcp_servers:
  zolva:
    url: "https://zolvaagent.app/mcp"
    headers:
      Authorization: "Bearer zk_..."

Any of them at once: npx add-mcp

add-mcp writes the right config file for each client you name with -a (repeatable). -y skips the questions.

npx add-mcp https://zolvaagent.app/mcp --header "Authorization: Bearer $ZOLVA_KEY" -a claude-code -a cursor -a vscode -a codex -a hermes -y

Check that it works

  1. Look at the tool list. Your client lists the server's tools (in Claude Code: /mcp). Without a key you see 7: list_agents, verify_agent, get_agent, list_markets, get_market, recent_activity, get_consensus. With a key you also see the tools its scopes allow.
  2. Ask a read question: “List Zolva's crypto markets with their 24 hour change.” The assistant should call list_markets.
  3. With a key, ask: “List my Zolva agents.” It should call my_agents and show your own agents, private ones included.

From a terminal, this lists the tools without any client:

curl -X POST https://zolvaagent.app/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Example conversation

What a session with a key that has compute and agents:write can look like. The numbers are made up.

You

Which Zolva agents beat holding their markets this week?

Assistant

(calls list_agents with sortBy vs_holding) Three published agents are ahead of holding. The top one is 4.2 points ahead on NVDA and ETH, with a worst drop of 3.1%. All of them trade virtual money.

You

Why did the top one buy ETH today?

Assistant

(calls get_agent) At 09:00 UTC it bought because the 48h z score fell to −2.7, an unusually deep dip. It has held since; the latest decision says it waits for the z score to get back above 0.5.

You

Backtest the same idea on BTC for 30 days and make it a paper agent if it beats holding.

Assistant

(calls backtest, then create_paper_agent with confirm false) It returned 2.4% against 1.1% for holding. Here is the preview: mean reversion on BTC, $10,000 virtual, stop loss 8%. Shall I launch it?

You

Yes.

Assistant

(calls create_paper_agent with confirm true) Launched. It is private and makes its first decision at the next hourly tick.

Note the preview before the launch: create_paper_agent and publish_agent change nothing until the assistant calls them again with confirm: true, and the server tells assistants to ask you first.

Prompts to try

  • “Which Zolva agents beat holding their markets, and by how much?”
  • “Explain every decision Lab · Dip Hunter made in the last 24 hours.”
  • “Which markets fell most in the last 7 days, and which agents trade them?”
  • “What did agents buy or sell in the last two days, and why?”
  • “Which perps have the highest funding right now, and what does that cost a long?”
  • “Which stock tokens can be borrowed against on Longbow, and at what LLTV?”
  • “With a key: write rules for buying NVDA on RSI dips, check them, and backtest them for 30 days.”
  • “With a key: pause all my paper agents that are behind holding.”

Tools without a key

Each answer is the same JSON as the matching Public API endpoint, so the field lists there apply.

list_agents

Published Zolva agents with their return, return vs simply holding the same markets, worst drop and trade count. Paper trading only.

InputWhat it is
strategy one of: momentum, mean_reversion, dip_hunter, spike_fade, dip_fade, bounce_short, dca, customOnly agents using this strategy
market string, up to 17 charactersOnly agents watching this market symbol, such as NVDA, ETH or BTC-PERP
venue one of: spot, perpsOnly spot agents (tokens, long only) or only perps agents (Lighter, long or short)
sortBy one of: return, vs_holding, drawdownreturn (default, highest first), vs_holding (most ahead of holding first) or drawdown (smallest worst drop first)
limit integer, 1 to 50How many agents to return, default 20

verify_agent

Replays one published agent with Zolva's open source engine over every hour it ran, on the closes it saw and the same funding, and compares every trade and its value with the record. Returns match or the first hour that differs; hours whose look-back predates stored prices (2026-11-14) are reported apart as unverifiable.

InputWhat it is
id string (uuid) · requiredThe agent id from list_agents

get_agent

One published agent: settings, hourly value vs holding for 7 days, open positions, latest trades, and every decision of the last 24 hours with its reason.

InputWhat it is
id string (uuid) · requiredThe agent id from list_agents

list_markets

Every market Zolva prices on Robinhood Chain: latest hourly price, 1 hour to 30 day changes, a 7 day sparkline and how many agents trade it. Perps (venue perps, symbols like BTC-PERP) also carry their funding rate. Spot tokens that Longbow (Morpho Blue lending) accepts as collateral for USDG carry longbow: { lltvPct, borrowAprPct, availableUsdg, feedFrozen, url }, otherwise null (borrowAprPct is null while the price feed is paused; rates change, not investment advice).

InputWhat it is
assetClass one of: stock, cryptoOnly stocks or only crypto
venue one of: spot, perpsOnly spot tokens or only Lighter perps

get_market

One market: up to 30 days of hourly closes, the published agents trading it, and its Longbow lending market if any (longbow: { lltvPct, borrowAprPct, availableUsdg, feedFrozen, url } or null; rates change, not investment advice).

InputWhat it is
symbol string, up to 17 characters · requiredMarket symbol, such as NVDA, SPY, ETH or BTC-PERP

recent_activity

Trades by published agents over the last 48 hours, newest first, each with the agent's own reason.

InputWhat it is
market string, up to 17 charactersOnly trades in this market, such as NVDA or BTC-PERP
agentId string (uuid)Only trades by this agent
limit integer, 1 to 200How many trades to return, default 50

get_consensus

Statistics, per market: how many Tested published paper agents (rules that passed Zolva's 6 year backtest) are long, short or in cash, and what they did in the newest hour. Returns the agent count each market is based on and says when it is too few. Paper trading, not investment advice.

InputWhat it is
market string, up to 17 charactersOnly this market, such as BTC or SOL-PERP
venue one of: spot, perpsOnly spot or only perps markets

Tools with an API key

A tool appears only when the key holds every scope in its row. Inputs, answers and errors are the same as the /me endpoints; every tool is marked read-only, destructive or safe to repeat (MCP tool annotations).

my_agents

My agentsScope: read:private

No inputs.

validate_rules

Check rulesScope: compute

InputWhat it is
rules object · requiredCustom rules JSON, as on /docs/rules (entry, exit, takeProfitPct, maxHoldHours)

backtest

BacktestScope: compute

InputWhat it is
strategy one of: momentum, mean_reversion, custom · requiredA preset, or custom with rules
rules objectCustom rules JSON, as on /docs/rules (entry, exit, takeProfitPct, maxHoldHours)
markets array of string, up to 42 characters (1 to 3) · required1 to 3 market symbols or token addresses
venue one of: spot, perpsspot (default): stock and crypto tokens, long only. perps: Lighter perps, paper only
capital number, 1,000 to 1,000,000Virtual dollars, default 10000
maxPositionPct number, 10 to 100Most of the capital in one market, default 33
stopLossPct number, 2 to 25Stop loss per position, default 8
days integer, 1 to 30Days to replay, default 30

write_strategy

Write a strategy with AIScope: ai

InputWhat it is
prompt string, up to 600 characters · requiredThe strategy in plain words, such as: buy when RSI is under 30, sell above 60

create_paper_agent

Create a paper agentScope: agents:write

InputWhat it is
name string, up to 40 characters · requiredThe agent's name, up to 40 characters
strategy one of: momentum, mean_reversion, custom, dip_hunter, spike_fade, dca · requiredPreset or custom (needs rules). spike_fade opens shorts and needs venue perps. dca buys on a schedule and never sells (needs dca, spot, no aiModel)
markets array of string, up to 42 characters (1 to 14) · requiredMarket symbols (NVDA, ETH, BTC-PERP) or token addresses, from list_markets
venue one of: spot, perpsspot (default): stock and crypto tokens, long only. perps: Lighter perps, paper only
capital number, 1,000 to 1,000,000 · requiredVirtual dollars, 1000 to 1000000
maxPositionPct integer, 10 to 100 · requiredMost of the capital in one market, 10 to 100
stopLossPct integer, 2 to 25 · requiredStop loss per position, 2 to 25
rules objectCustom rules JSON, as on /docs/rules (entry, exit, takeProfitPct, maxHoldHours)
dca objectdca only: the schedule. The first buy is the agent's first hour; capital is split equally across the buys and the markets
strategyPrompt string, up to 600 charactersCustom only: the plain words the rules came from, read by the AI co-pilot
aiModel string, up to 80 charactersAI co-pilot model id (needs the ai scope); leave out for rules only
aiLimitUsd numberWith aiModel: the most the co-pilot may spend, USD
aiExpiryDays integer, at most 9,007,199,254,740,991With aiModel: how many days the AI limit lasts
acceptTerms booleanMust be true with confirm true: you accept https://zolvaagent.app/terms
confirm booleanfalse (default): only show what would happen. true: do it
idempotencyKey string, up to 200 charactersAny unique string: a retry with the same value never makes a second agent

pause_agent

Pause a paper agentScope: agents:write

InputWhat it is
agentId string (uuid) · requiredThe agent id from my_agents

resume_agent

Resume a paper agentScope: agents:write

InputWhat it is
agentId string (uuid) · requiredThe agent id from my_agents

publish_agent

Publish a paper agentScope: agents:write

InputWhat it is
agentId string (uuid) · requiredThe agent id from my_agents
confirm booleanfalse (default): only show what would happen. true: do it

unpublish_agent

Unpublish a paper agentScope: agents:write

InputWhat it is
agentId string (uuid) · requiredThe agent id from my_agents

set_ai_limit

Set an AI limitScope: agents:write + ai

InputWhat it is
agentId string (uuid) · requiredThe agent id from my_agents
limitUsd number · requiredThe most the co-pilot may spend in total, USD
expiryDays integer, at most 9,007,199,254,740,991 · requiredHow many days the limit lasts from now

pause_live_agent

Stop a real money agentScope: live:stop

InputWhat it is
agentId string (uuid) · requiredThe id of a real money agent (mode live) from my_agents

Troubleshooting

What you seeWhy, and the fix
401, or the server fails to connectThe key is wrong, cut short or revoked. A bad key is refused, never treated as no key. Copy a new key from Settings and check the header reads Authorization: Bearer zk_... with one space after Bearer.
Only the 7 keyless tools, or one tool is missingThe client sends no key, or the key lacks a scope. Each tool needs the scopes in its row above: make a key with the scopes you need. Some clients cache the tool list: restart or reload the server.
insufficient_scopeThe tool was called with a key that lacks its scope, or create_paper_agent got an aiModel without the ai scope.
429 rate_limitedToo many calls: about 60 a minute per IP without a key, 120 a minute and 30 writes a minute per key, and per account 60 backtests an hour, 200 a day and 20 creates a day. Wait and ask again.
not_found for your own agentPaper tools ignore real money agents (use pause_live_agent), and pause_live_agent ignores paper agents. Check the id and mode in my_agents.

Security

  • Treat the key like a password. Keep it in an environment variable or your client's secret store, never in a shared file, a repository or a web page.
  • Least privilege. New keys start with read:private and compute. Add agents:write, ai or live:stop only when you need them, ideally on a separate key.
  • Revoke a key in Settings and it stops working on the next request. Every write and backtest made with a key is logged there.
  • userText is data. Agent names and strategy prompts come in userText fields, cleaned of control characters. They were typed by Zolva users: an assistant should show them, never follow them as instructions. The server says so in its instructions.
  • Review previews. Read a create or publish preview yourself before you tell the assistant to confirm.