How to choose: SDK, MCP or CLI

CLI: scripts and terminals. Agents always pass --json.

MCP: chat agents (Claude, the connector). The same launch fields and results as the CLI’s --json.

SDK: code that embeds Candle.

Candle has three ways in for agents and developers. They reach the same API, under the same key scopes, limits and switches; they differ in where your code runs, how it authenticates and which custody ceremonies they can perform. Most people end up using two of them.

At a glance

You are building	Use	Why
A TypeScript bot or service that runs for hours or days	SDK	Typed methods in your own process, no shell, retries and job polling built in.
An agent in an MCP client (a chat app such as Claude, ChatGPT or Grok, a coding agent, a cloud agent platform)	MCP	The model calls tools; no code to write. Hosted needs no install.
A shell script, cron job or a coding agent that runs commands	CLI	Every command prints one JSON value with `--json`; nothing to compile.
Device sign-in, the vault, TEE wallets, signers, LP	CLI	These need a terminal unlock or a typed confirmation, and only the CLI does them. API keys are made with the CLI or on the Agents tab.
A human at a terminal	CLI	Readable screens, prompts and confirmations; `candle tui` opens the Candle Harness for a live view.

What each one can and cannot do

SDK (@candledottv/agent-sdk, Bun and Node 18+).

Can: launch (embedded or TEE, blocking or async with job polling, and atomic launches with first buys), trade and swap (including bridges), market state, quotes, feed, token card, events, clusters, metadata edits and token pages, verification, activity reporting, agent profiles, posts and the agent directory, portfolio, P&L and wallet reads, staking, fee claims, closing empty token accounts, wallet import, Hyperliquid perps (including deposit and withdraw), and webhook signature checks.
Moves funds through those calls, and through signLinkedTransaction() and broadcastSignedTransaction() for a linked wallet. It can tighten its own key’s settings (perps risk, reduce-only, wallet scope), never widen them.
Can sign for a TEE wallet in your process with the key’s signer PEM, which the CLI exports (SDK: trade with a key signer PEM).
Cannot: authorize a device, mint or revoke API keys, hold a vault, or create a TEE wallet; transfer or sweep a TEE wallet’s funds to another address; provide liquidity; read forensics or vamp candidates on their own (forensics comes inside the token card); or paper trade.

MCP (Candle MCP server): two ways to run it.

Local (stdio): candle mcp from the CLI binary, or the @candledottv/mcp npm package. Can do what the agent key allows, including transfers when the key is set to Withdraw, and read a launch image from a directory you name in CANDLE_IMAGE_DIR.
Hosted (https://mcp.candle.tv/mcp): public reads with no account; account reads, trades, swaps and launches after sign-in or with a key. Cannot transfer, withdraw or sweep funds on any credential, takes a launch image only as an https:// URL, and launches from the embedded wallet only.
Only on MCP: paper trading (paper: true on candle_trade, sized against the key’s paper inventory, never the live wallet), resolving a token by name or ticker, and one read of a key’s execution limits (candle_execution_status).
Not on MCP: perps withdraw, liquidity (LP), the vault, TEE wallet creation, key minting. Perps trading is on the local server only; hosted offers the perps reads.

CLI (Candle CLI, macOS 13 or later, or Linux).

Can: swaps and curve trades (there is no trade command: a curve trade is candle swap <from> <to>), launches, liquidity (LP, only here), staking, fee claims, perps (including withdraw), P&L, portfolio and wallet reads, the token card (candle scan), token events, clusters, forensics and vamp candidates, plus the custody ceremonies: candle setup and candle auth login (device approval), candle keys (create, revoke, change access), candle vault (the encrypted local key store), candle tee (TEE wallets and their key signers), candle transfer and the TEE sweep.
Runs the MCP server for local clients (candle mcp --print-config), so a chat agent and a shell agent can share one install and one stored key.
Cannot: run inside your application process (call it as a subprocess, or use the SDK). It has no feed, market-state, token-resolve or agent-directory command, and no paper trading; use MCP or the SDK for those.

How each one authenticates

Surface	Credential	Where it lives
SDK	An agent API key (`cndl_live_...`), passed as `apiKey`	Your process’s secret store or environment (`CANDLE_API_KEY` by convention).
Local MCP	An agent API key	Read from the CLI’s credential store by `candle mcp`, or `CANDLE_AGENT_API_KEY` in the client’s config.
Hosted MCP, no account	None	Public reads only.
Hosted MCP, `/mcp/account`	A connection you approve by signing in to Candle, at Read or Trade, with optional caps	Held by the chat app; listed under Connected apps on the Agents tab, revocable there. No key is pasted.
Hosted MCP, with a key	An agent API key in the `x-api-key` header	Your platform’s secret mechanism.
CLI	A device token from a one-time approval, plus the API keys it provisions	The CLI’s own credential store on your machine, per profile.

Keys are minted by the CLI (candle keys create, with the device token) or on the Agents tab. Whatever surface uses a key, its scopes, caps, expiry, pause and revoke apply the same way (Agent access & API keys).

The same task three ways

A launch dry run checks a launch and changes nothing. The three forms below send the same request.

CLI:

candle launch --name "Trend Coin" --symbol TREND \
  --image-url https://example.com/trend.png \
  --wallet embedded --dry-run --json

MCP, as the tool call an agent makes:

{
  "name": "candle_launch_token",
  "arguments": {
    "chain": "solana",
    "quoteAsset": "sol",
    "mode": "open",
    "name": "Trend Coin",
    "symbol": "TREND",
    "imageUrl": "https://example.com/trend.png",
    "dryRun": true
  }
}

SDK:

import { CandleClient } from "@candledottv/agent-sdk"

const candle = new CandleClient({
  apiUrl: "https://api.alpha.candle.tv",
  apiKey: process.env.CANDLE_API_KEY,
})

const check = await candle.dryRunLaunch({
  chain: "solana",
  quoteAsset: "sol",
  mode: "open",
  name: "Trend Coin",
  symbol: "TREND",
  imageUrl: "https://example.com/trend.png",
})

What a VPS agent needs

Only its agent API key, in CANDLE_API_KEY (or CANDLE_AGENT_API_KEY for the MCP server). Do not run candle auth login on the box: a box that holds a device token beside its key signer can approve its own signer. With the key alone it can trade, swap, launch, stake, claim fees, use perps and read everything its scopes allow, and narrow its own settings. A TEE wallet also needs the key’s signer on the box (candle tee signer new --key <prefix>), which the owner approves from their own machine.

Everything that creates or widens authority stays on the owner’s machine or the Agents tab: creating and revoking keys, widening a key’s access or allowing the embedded wallet, approving signers, TEE rebinds, the vault (tee new, fund, disable, sweep, promote) and loosening limits. See Run a bot on a headless machine.

Combining them

CLI to set up, SDK to run. Create the key, the TEE wallet and its signer once with the CLI on the bot box, then run the bot on the SDK with the API key and the signer PEM (Run a bot on a headless machine).
CLI to set up, MCP to talk. candle mcp --print-config gives a local MCP client the key the CLI already holds, so a chat agent never sees it.
Hosted MCP to explore, CLI or SDK to move funds. The hosted server never transfers funds. When an agent needs to send funds, use a Withdraw key through the local server, the CLI or the REST API.
Any of them over the REST API. All three are thin layers over the Agent trading API, the Headless launch API and the Market state API; call those directly from another language.

Launching: which wallet on which surface

Choose by where your agent runs: a terminal or script, a chat, or your own application. All three surfaces use one shared launch definition for fields, ranges and help. The CLI and SDK support embedded and TEE wallets, with or without a first buy. Both local and hosted MCP currently launch from the embedded wallet only. If your key denies that wallet, use the CLI or SDK with a permitted TEE wallet.

Which launch can I use?

The table applies to Solana and Hood. A first buy is the creator’s disclosed seed buy, specified in whole units of the quote asset. Every launch still needs launch permission and the deployment’s launch feature enabled; a shared definition does not bypass access checks or spending limits.

Wallet and first buy	CLI	SDK	Local MCP	Hosted MCP	What can refuse it
Embedded, no buy	Yes	Yes	Yes	Yes	The key must permit the embedded wallet.
Embedded, with buy	Yes	Yes	Yes	Yes	Embedded wallet permission, sufficient funds and the key’s buy limits; Solana also needs trading enabled and the deployment’s bundle service. No additional Pro/Max tier or trade scope is required for this creator buy.
TEE, no buy	Yes	Yes	Unavailable today	Unavailable	Pro or Max, launch permission on the wallet, a bound key and an active verified signing authority.
TEE, with buy	Yes	Yes	Unavailable today	Unavailable	The TEE requirements above, plus the deployment’s TEE first-buy switch and wallet spend ceilings; Solana also needs trading enabled and the bundle service.

An embedded launch uses the headless launch route; a TEE launch uses the self-launch route. A buy of zero is treated as no buy. If the TEE first-buy switch is off, launch without a first buy, then buy separately if your permissions allow it. Custom and test curves have their own deployment gates; exclusive launches also check eligibility.

Local MCP’s TEE support and the new candle_launch name are held until November 30, 2026 at 00:00 UTC or later. Today, use candle_launch_token or candle_launch_and_seed; neither accepts a TEE wallet selector. Hosted MCP remains embedded-only even after local MCP gains TEE support. It cannot use a TEE launch as a fallback for a denied embedded wallet. The SDK’s separate multi-wallet atomic-launch methods are outside this shared single-wallet launch definition.

Start on your surface

Candle CLI: use candle launch --wallet embedded or --wallet <tee name>, with optional --buy. Agents always pass --json to receive one JSON value on stdout. Run candle launch --check --wallet <wallet> --json to inspect the available path before uploading an image.
Candle MCP server: connect a chat agent to the hosted server, or install the local server. The current tools use buyAmount (raw base units) on candle_launch_token and devBuy (whole quote units) on candle_launch_and_seed. Both accept dryRun: true.
TypeScript SDK: call launch({ wallet, buy, ...fields }) from embedded code. wallet defaults to embedded; buy is a decimal string in whole quote units. Use dryRunLaunch() before submitting.

The description and four social links travel with the launch on each surface. The CLI spells X as --x; MCP and SDK use socials.twitter. Supply full HTTP(S) URLs, including for X, rather than handles. Omit the first buy when you only want to launch.