Getting Started

Getting Started

Three steps: mint an API key in the 2DAI dashboard, add the server to your MCP host, then ask your agent to run get_account to confirm everything is wired up.

1. Mint an API key

1. Have a 2DAI account — sign up at 2dai.io with your email, or sign in with your wallet. Any active account can create keys.
2. In the dashboard's left sidebar, open Integrations.
3. Switch to the API keys tab and click + New key.
4. In the New API key dialog, fill in:

   • Label — a name for this integration (e.g. claude desktop, cursor laptop). Labels are how you tell keys apart later.

   • Scopes — what the key is allowed to do. Least privilege wins:

     Scope	Pick it when…
     read + generate	The minimum for this server. read covers listing, search, stats, downloads and queue checks; generate covers all the generate_* tools plus upload_image and cancel_generation.
     manage	You want the agent organising your drive — move, trash, restore, like, batch actions, folders and sidebar groups.
     publish	Opt-in. Only if you want the agent posting to (or pulling from) the public feed on your behalf.
     finance	Opt-in, read-only. Unlocks the wallet tools (get_wallet_status, get_lock, get_wallet_history). Never pre-selected, and no tool on this server can move money regardless — see Stats & Wallet.

   • Spend cap (optional) — a per-key USD ceiling. Your account credit is always the real limit; the cap just stops one key (one agent) from spending more than you allow.

5. Create it, then copy the secret immediately — the full key (2dai_sk_…) is shown once. If you lose it, revoke and mint a new one.

2. Add the server to your host

Two transports are supported and they expose the exact same tools:

• stdio via npx (local) — Node 18+ required, key stays on your machine, nothing to host. Best when you want zero third-party dependency.
• Hosted HTTP at mcp.2dai.io:800 — no install, no Node runtime, just a URL plus a Bearer key. Best when you want the fastest possible setup.

Both routes are covered below. Pick one.

stdio (npx)

The server runs locally over stdio via npx. The key is read from the TWODAI_API_KEY environment variable only — it is never passed as a tool argument, so it never appears in the model's context.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop:

{
  "mcpServers": {
    "2dai": {
      "command": "npx",
      "args": ["-y", "2dai-mcp-server"],
      "env": { "TWODAI_API_KEY": "2dai_sk_..." }
    }
  }
}

Claude Code

claude mcp add 2dai --env TWODAI_API_KEY=2dai_sk_... -- npx -y 2dai-mcp-server

Cursor

Add the same block to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "2dai": {
      "command": "npx",
      "args": ["-y", "2dai-mcp-server"],
      "env": { "TWODAI_API_KEY": "2dai_sk_..." }
    }
  }
}

Any other stdio host (Cline, Windsurf, …)

Every MCP host that speaks stdio takes the same three ingredients, whatever its config file is called:

{
  "command": "npx",
  "args": ["-y", "2dai-mcp-server"],
  "env": { "TWODAI_API_KEY": "2dai_sk_..." }
}

Hosted HTTP — mcp.2dai.io:800

Every host that speaks remote MCP (Streamable HTTP) can point at the hosted server instead of running npx locally. Same tools — minus a disk of yours: savePath and upload path are refused there, download_creation returns downloadUrl instead and uploads take base64. Same behavior otherwise, same account — just delivered over HTTP.

• Endpoint — https://mcp.2dai.io:800/mcp
• Auth — Authorization: Bearer 2dai_sk_... on every request (the key is sent per-request in the header; the server never stores it and each request is its own end-to-end session).

Claude Desktop / Cursor / Cline / Windsurf (remote-MCP JSON shape — some hosts still spell the type "remote" instead of "streamable-http", check their docs):

{
  "mcpServers": {
    "2dai": {
      "type": "streamable-http",
      "url": "https://mcp.2dai.io:800/mcp",
      "headers": { "Authorization": "Bearer 2dai_sk_..." }
    }
  }
}

Claude Code

claude mcp add --transport http 2dai https://mcp.2dai.io:800/mcp \
  --header "Authorization: Bearer 2dai_sk_..."

Note: hosted mode does not read any of the TWODAI_* environment variables listed below — the client sends only the auth header, and the server picks its own defaults for previews, wait budget, etc. Use stdio if you need to tune those knobs locally.

3. First-call sanity check

Ask your agent:

Run get_account on the 2dai server.

You should get one line back — account name, available credit, tier, and the key's label, scopes and spend cap:

Account yourname — $12.40 credit, tier tier2. Key "claude desktop" has
scopes [read, generate, manage]; no cap on this key. image presets: fast,
normal, high, max (recommended) — locked on this tier: ultra, ultimate. Gen8
Preview images (generate_image with imageModel "next", up to 6 refCreationIds,
legible text, priced on render time at roughly 4–7× the Gen 7.2 preset): Gen8 Preview images presets: fast,
normal, high, max (recommended) — locked on this tier: ultra, ultimate.
video presets: fast, normal, high, max — locked on this tier: ultra,
ultimate. Video durations: 5s (recommended), 6s, 7s (locked); default 5s.
Gen8 Preview video (videoModel "next", with sound) durations: 1s, 5s (recommended),
8s, 10s, 12s (locked), 15s (locked), 17s (locked), 20s (locked); default 5s.
Gen8 Preview video presets: fast — locked on this tier: normal, high, max, ultra,
ultimate. An MP3 uploaded with upload_audio can be its audio reference
(audioCreationId + audioUse "music" / "voice"). Prompts up to 4000
characters on this account (Believer raises it to 6000). Powered by 2DAI's
Gen 7.2 model on the 2DAI Private Cloud — and the Gen8 Preview engines, Gen8
Preview video (the next video engine with sound, generate_video videoModel
"next"), Gen8 Preview images (generate_image imageModel "next").

The preset and duration lines are the account's real access, for Gen 7 and for both Gen8 engines (Gen8 Preview images and Gen8 Preview video): an agent picks from them instead of discovering locks by submitting. Locked entries are listed too, so the agent can tell the user which tier opens them (Dashboard → Tiers). The package also ships a skill for agents — skills/2dai/SKILL.md in node_modules/2dai-mcp-server/ — that explains the platform, the presets and the film recipe.

If instead you see a key or scope error, Troubleshooting has the fixes. From here, try:

Generate a 16:9 image of a lighthouse at dusk, then show it to me.

Configuration (env)

All optional except the key. Set these in the same env block:

Variable	Default	Meaning
TWODAI_API_KEY	— (required)	Your 2DAI API key
TWODAI_PREVIEWS	1	Attach downscaled inline previews to finished generations so the model can see them. 0 disables
TWODAI_PREVIEW_MAX_SIDE	512	Longest edge of those previews, in px (64–2048; aspect ratio preserved)
TWODAI_WAIT_BUDGET_MS	45000	How long a generation call blocks before degrading to a queueId (see Generating); 0 = never block
TWODAI_IDEMPOTENCY_WINDOW_MS	30000	Window in which an identical re-submit is treated as a retry, not a new charge
TWODAI_FILE_ACCESS	cwd	What upload_image / upload_audio / download_creation file paths may touch: cwd (confined to the working directory), any (no boundary; TWODAI_ALLOW_ANY_PATH=1 still means this), none (no filesystem — uploads by base64, downloads by downloadUrl; the hosted server's mode). See Library & Drive
TWODAI_API_BASE	production API	API origin override (for self-hosted testing)