Skip to main content

MCP Integration

Connect AI agents — Claude Code, Claude Desktop, Cursor, and any other MCP-compatible client — directly to your VolatiCloud account. Manage strategies, launch backtests, and control live bots through natural language, with no API glue code, no service-account credentials, and no shared secrets in your repo.

What Is the Model Context Protocol?​

The Model Context Protocol (MCP) is an open standard that gives AI agents a live, typed connection to external systems. Instead of describing the API in a prompt and hoping the model generates the correct HTTP call, MCP hands the assistant a structured catalogue of tools. The agent discovers what's available, picks the right operation for your request, validates arguments against the operation's schema, and calls it directly — all inside a single conversation.

VolatiCloud's MCP server exposes the full GraphQL API as a set of tools, authenticates through the same Keycloak OAuth that powers the dashboard, and runs on hosted infrastructure at mcp.volaticloud.com. There is nothing to install or maintain locally — the agent just needs the URL and a browser for the first sign-in.

What you can do with it​

  • List and inspect your bots, strategies, exchanges, runners, and backtests
  • Create, update, and delete any resource the GraphQL API supports
  • Launch backtests and hyperopt runs and fetch their results
  • Start, stop, and monitor live bots including open positions and trading config
  • Query historical trades and recent alert events
  • Run raw GraphQL via an escape hatch for anything the typed tools don't cover

Any operation you can perform in the dashboard, the agent can perform too — scoped to the same organization and authorization rules you already have.

Prerequisites​

  • A VolatiCloud account and an organization — sign up at console.volaticloud.com
  • A modern MCP client (Claude Code, Cursor, or Claude Desktop with the mcp-remote bridge)
  • A browser on the machine running your agent — the first connection opens an OAuth consent page

No API keys or client secrets to generate. The server uses OAuth 2.0 PKCE, so authentication happens in your browser the first time you connect, and your agent stores the session token after that.

Quick start — Claude Code​

  1. Open your project in Claude Code.

  2. Create or edit .mcp.json in the project root (or the equivalent in your global Claude Code settings).

  3. Paste this configuration:

    {
      "mcpServers": {
        "volaticloud": {
          "type": "http",
          "url": "https://mcp.volaticloud.com/mcp"
        }
      }
    }

  4. Restart Claude Code. The first time you use a VolatiCloud tool, Claude Code opens a browser window to authenticate you through Keycloak. Sign in, approve the consent screen, and return to Claude Code — the tools are now live.

That's it. You can ask things like:

"List all my running bots and their current 7-day PnL."

Setup by client​

Claude Code​

Same as the Quick Start above. The type: "http" field tells Claude Code to use the streamable-HTTP transport directly — no local bridge needed.

Cursor​

Cursor uses the same JSON format. Open Settings → Features → MCP Servers and add:

{
  "mcpServers": {
    "volaticloud": {
      "type": "http",
      "url": "https://mcp.volaticloud.com/mcp"
    }
  }
}

Restart Cursor. The first tool call triggers the browser OAuth flow.

Claude Desktop​

Claude Desktop doesn't yet support streamable-HTTP MCP transport directly, so it needs a small bridge to proxy the hosted endpoint through a local stdio process. Use mcp-remote, which ships via npm and requires Node.js 18+:

{
  "mcpServers": {
    "volaticloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.volaticloud.com/mcp"]
    }
  }
}

Paste this into Claude Desktop's config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Then fully quit and reopen Claude Desktop. The bridge handles the OAuth PKCE flow for you; the browser opens on first use.

How it works​

  1. Your agent connects to mcp.volaticloud.com/mcp over HTTPS.
  2. On first use, it starts an OAuth PKCE flow in your browser against VolatiCloud's Keycloak. You sign in with your normal VolatiCloud credentials.
  3. Keycloak returns a short-lived JWT to your agent. The agent stores it in memory for the session.
  4. Every tool call forwards that JWT to the GraphQL backend. All the usual authorization rules (role, scopes, view-secrets) apply.
  5. The MCP server returns the typed result to your agent, which formats it as natural language in your conversation.

The server introspects the GraphQL schema once per authenticated session and caches it for the lifetime of your connection. There's no stale-tools problem — if a new GraphQL operation ships, your next MCP session picks it up automatically.

Available tools​

The VolatiCloud MCP server registers four core tools unconditionally, then lazily resolves individual GraphQL operation tools on demand.

Core tools (always available)​

ToolDescription
introspect_schemaExplore the GraphQL schema and drill into specific types
search_schemaSearch types, fields, and enums by keyword
execute_graphqlRun any GraphQL query or mutation with variables
resolve_toolMaterialize the parameter schema for a named operation on demand

Operation tools (resolved on demand)​

Every query and mutation in the GraphQL schema is available as an individually-typed tool. A typical agent workflow looks like this:

  1. Agent calls search_schema with "bot" to discover bot-related operations.
  2. Agent calls resolve_tool with the operation name (e.g. createBot) to fetch the typed parameter schema.
  3. Agent calls the resolved tool with validated arguments.

This lazy pattern keeps the initial tools/list response small — only the four core tools — so agents don't pay a large token cost just to connect. Tool schemas are resolved per-session and cached, so repeated calls within a conversation don't round-trip.

Examples of operations you can resolve:

CategoryOperations
Liststrategies, bots, exchanges, runners, backtests
CreatecreateStrategy, createBot, createExchange, createRunner
UpdateupdateStrategy, updateBot, updateBacktest
DeletedeleteStrategy, deleteBot, deleteBacktest
Bot lifecyclestartBot, stopBot, restartBot
AnalysisrunBacktest, runSimulation, runHyperopt
Live datagetBotOpenPositions, getBotTradingConfig, getBotTrades

Example prompts​

Once connected, try these as starting points:

  • "List all my bots and their 7-day PnL. Flag any that are losing money."
  • "Create a backtest for my RSI-MR-01 strategy on BTC/USDT over the last 90 days with a 100 USDT stake."
  • "Show me the last 10 trades on BOT-001, and tell me if any of them exceeded the strategy's stop loss."
  • "Stop every bot running on the Bybit exchange and confirm they've closed all open positions."
  • "Walk me through creating a MACD trend-follower strategy and deploying it to a dry-run bot on Kraken."

The agent discovers the right tools, calls them in order, and returns the results inline. If it needs a follow-up — for example, fetching trade history for a specific bot — it chains the calls automatically in the same conversation.

Authentication and security​

OAuth PKCE via Keycloak. The first time your agent calls a VolatiCloud tool, it opens your browser to the VolatiCloud Keycloak login page. You sign in the same way you would for the dashboard, approve the MCP consent screen, and the agent receives a short-lived JWT. No credentials are ever written to disk by the agent itself.

Your permissions, enforced server-side. The JWT identifies you, and every GraphQL operation the MCP server calls is subject to the same authorization rules that apply in the dashboard. If you can't delete a bot through the UI, the agent can't delete it through MCP either.

No local API keys. The hosted architecture means there's nothing in your .mcp.json file that would let someone else access your account. If your config is committed to a public repo, the worst someone can do is connect to the MCP server and then fail the authentication step themselves.

Sensitive fields are gated. Fields like exchange API secrets and bot credentials require the view-secrets scope. Even once authenticated, your agent can only read the fields your role allows.

tip

When using Claude Code in a team setting, each developer authenticates with their own VolatiCloud account. The MCP session is per-user, not per-repo, so there's no shared credential to rotate if someone leaves the team.

Troubleshooting​

"Tool call failed: not authenticated"​

Your JWT has expired or the session was never established. Trigger a tool call and complete the browser flow when it opens. If the browser doesn't open automatically, check your agent's logs for an authentication URL you can open manually.

"MCP server not found" in Claude Desktop​

Claude Desktop needs the mcp-remote bridge, not a direct HTTP URL. Verify your config uses the command/args shape with npx -y mcp-remote ..., not the type: "http" shape used by Claude Code and Cursor.

Browser opens but the callback fails​

The OAuth callback redirects to a local port on the agent machine. If you're running your agent inside a VM or WSL without port forwarding, the callback can't reach the agent. Running the agent on the same host where the browser runs avoids this entirely.

Agent says the tool doesn't exist​

Ask the agent to run search_schema or introspect_schema first to discover the correct operation name. Most operations are camelCased (for example, createBot rather than create_bot).

Rate limits​

The hosted MCP endpoint applies per-user rate limits that match the normal GraphQL API. Heavy batch operations (hundreds of reads per minute) may throttle — prefer execute_graphql with a selection set that returns multiple resources in one call when possible.