Candle MCP server

Candle ships an MCP (Model Context Protocol) server, @candledottv/mcp, that exposes the agent rail as fifteen tools over stdio. An MCP-capable agent can launch tokens (with or without a bundled dev buy), trade and swap them, move and sweep balances, read market and feed data, run launch forensics, report on-chain activity, and check an agent profile without hand-rolling HTTP calls.

The server is a thin wrapper: five of the tools map to exactly one REST request against the Candle API, and the response body is handed back to the caller unchanged, error responses included. Everything the tools can do, you can also do directly against the Headless launch API, Agent trading API, and Market state API.

Tools

Tool	REST call	Needs a key
candle_launch_token	POST /api/v1/launch/headless, or /dry-run when called with dryRun: true	Yes
candle_launch_and_seed	The headless launch with a devBuy bundled into the launch transaction, plus an optional follow-up trade	Yes
candle_trade	The Agent trading API build-and-confirm flow, one tool call	Yes, with swap:write
candle_get_market	GET /api/v1/markets/:chain/:mint	No
candle_resolve_token	GET /api/v1/markets/:chain/:mint, with the chain read off the address	No
candle_get_feed	GET /api/v1/markets/feed?bucket=...	No
candle_report_activity	POST /api/v1/activity/report	Yes
candle_get_agent_profile	GET /api/v1/users/:idOrWallet/agent	No
candle_get_wallets	GET /api/v1/agent/wallets/embedded	Yes
candle_execution_status	The embedded wallets, the tier and this key’s own limits, in one call	Yes
candle_get_operation	GET /api/v1/trade/agent/jobs/:clientTradeId, or the launch rail’s /jobs/:clientLaunchId	Yes
candle_token_forensics	GET /api/v1/markets/:chain/:mint/forensics	No
candle_swap	POST /api/v1/agent/swap	Yes
candle_transfer	POST /api/v1/agent/transfer	Yes
candle_sweep	Sweeps an account’s base assets, orchestrated over the transfer endpoint	Yes

The five keyless reads are the reason to install this server before you have an account: point any MCP client at it and an agent can browse feeds, market state, launch forensics, agent profiles, and resolve a bare contract address with no signup. The Agent quickstart starts there.

candle_launch_token accepts the same fields as the headless endpoint (clientLaunchId, chain, quoteAsset, mode, stakerAllocationBps, dexVersion, buyAmount, name, symbol, imageUrl, and the rest), plus dryRun: true to validate a launch without spending anything.

Several rail features are REST-side only and are not exposed as tools: async launches with job polling, hosted image uploads, atomic launches, server-side /submit, linked cross-chain swaps, limit orders, and the key-management routes. All are documented on the Headless launch API and Agent trading API pages. If you want the whole surface as typed methods rather than tools, see the TypeScript SDK.

Doing a job end to end

A human says “buy 0.2 SOL of 9dXSV8...CNDL”. That is four calls:

1. candle_execution_status {} confirms the key can trade and shows the wallets it spends from. If it reports a read as unreadable, fix that first rather than inferring readiness from a failed trade.
2. candle_resolve_token { "mint": "9dXSV8...CNDL" } returns the token and its chain. The chain comes from the address’s own shape, so it never has to be supplied or guessed.
3. candle_trade { "mint": "9dXSV8...CNDL", "side": "buy", "amount": "0.2" }. amount is decimal and denominated in the token’s own quote asset. Keep the clientTradeId from the result.
4. Only if step 3 times out: candle_get_operation { "kind": "trade", "clientId": "<that id>" }. A 404 means Candle never saw the id, so nothing moved and the original request is safe to send again unchanged.

Selling a fraction is the same shape with { "side": "sell", "percent": 50 }.

Environment

Variable	Meaning
CANDLE_API_URL	Base URL of the Candle API. Must be https://, since every writing tool sends the key: a cleartext http:// URL to a non-loopback host is refused at startup. Loopback (localhost, 127.0.0.0/8, ::1) is always allowed, so developing against a local API needs no opt-in.
CANDLE_ALLOW_INSECURE_HTTP	Set to any non-empty value to allow an http:// URL to a non-loopback host, for a trusted local endpoint that is not loopback (a devcontainer reaching its host, say). Not for anything that leaves the machine.
CANDLE_MCP_TOOLS	A comma-separated allowlist of tool names. Unset means every tool. The server fails at startup on an unknown name rather than silently registering the wrong set. candle mcp --read-only and candle mcp --tools <a,b,c> set this for you.
CANDLE_AGENT_API_KEY	An agent API key (cndl_live_... or cndl_test_...). Required by the ten tools that need an account, seven of which move funds and three of which only read it (candle_get_wallets, candle_execution_status, candle_get_operation); the five keyless tools work without it. CANDLE_API_KEY is accepted as an alias (the CLI and SDK use that name); when both are set, CANDLE_AGENT_API_KEY wins.

See Agent access & API keys for how to issue a key, or run candle auth login from the CLI to be provisioned one from the terminal.

Client configuration

There are three ways to run it. All three speak the same protocol over stdio; they differ only in what has to be installed and where the key comes from.

With the Candle CLI (recommended)

The CLI has the server built into its binary, so there is nothing extra to install and no Node runtime needed on the host. It also reads the API key from the CLI’s own credential store at launch, which means the key never sits in a config file at all:

candle mcp --print-config

That prints the client block filled in for your install, with an absolute path to the binary (MCP clients spawn servers from their own working directory and with their own environment, so a bare command name usually fails in GUI hosts):

{
  "mcpServers": {
    "candle": {
      "command": "/Users/you/.local/bin/candle",
      "args": ["mcp"]
    }
  }
}

candle mcp --read-only pins the server to the five keyless read tools; candle mcp --tools <a,b,c> takes an explicit allowlist.

From npm

@candledottv/mcp is published, so any MCP client can spawn it directly. This needs Node on the host and puts the key in the config file:

{
  "mcpServers": {
    "candle": {
      "command": "npx",
      "args": ["--yes", "@candledottv/mcp"],
      "env": {
        "CANDLE_API_URL": "https://api.alpha.candle.tv",
        "CANDLE_AGENT_API_KEY": "cndl_live_..."
      }
    }
  }
}

Omit CANDLE_AGENT_API_KEY entirely for a keyless, read-only server.

From a clone

For working on the server itself:

git clone https://github.com/candledottv/agentic.git
cd agentic
bun install
bun run --cwd packages/mcp build

Then point the client at packages/mcp/dist/index.js with node, using an absolute path.

Error shapes

The server never reinterprets an error body, and the body is not one uniform shape across the tools:

• candle_launch_token, candle_launch_and_seed, candle_get_market, and candle_get_feed hit endpoints that use the structured envelope { "success": false, "error": { "code", "message", ... } }. Branch on error.code; the full code table is in the Headless launch API.
• candle_trade wraps the trade endpoint’s body verbatim under api, alongside the echoed clientTradeId, so the Agent trading API error codes apply unchanged.
• candle_report_activity relays its endpoint’s plain shape verbatim: { "error": true, "payload": "..." }.
• candle_get_agent_profile relays its endpoint’s plain shape verbatim: { "error": "..." }.

Two failure modes are worth handling explicitly, because neither is fixed by retrying or by asking for more scopes: KEY_EXPIRED (401) means the key passed its expiresAt and only a new key recovers, and KEY_LIMIT_REACHED (403, from candle_trade) means the key’s own transaction-volume cap is used up, carrying resetsAt.