Elixium Logo
elixium.aiHumans Approve · AI Executes

Agent Integration

Connect Elixium to Claude and your AI coding assistants. Access your backlog, update stories, and get AI guidance — from the Claude app in one click, or from your IDE.

🔌 One Integration, Every AI Agent

Elixium uses the Model Context Protocol (MCP) — the universal standard adopted by GitHub Copilot, Claude, Cursor, Gemini, and more. Configure once, use everywhere.

Two ways to connect — pick your agent

  • Claude (Desktop, Web, Code): add the hosted connector — one URL, sign in with OAuth. No API key, no JSON, nothing to install. (Right below.)
  • VS Code, Copilot, Cursor, Codex, Windsurf — or self-hosted / air-gapped: the Elixium AI Companion VS Code extension — sign in, pick a board, done. (Further down.)

🟠 Claude (Desktop & Web): One-Click Connector

For the Claude desktop app and claude.ai, connect Elixium as a remote MCP connector: paste one URL and sign in. No API key, no config files, nothing to install.

  1. In Claude, open Settings → Connectors → Add custom connector.
  2. Paste the connector URL:
    https://connect.elixium.ai/mcp
  3. Click Add, then Connect — Claude opens an Elixium sign-in page.
  4. Sign in (Google, GitHub, or Microsoft), choose the workspace to connect, and click Allow.
  5. Done — Claude can now read and update that workspace's board. Try: "What stories are in Current?"

Why the connector beats a pasted key: you sign in with OAuth 2.1 instead of copying an API key. The connection is scoped to the one workspace you pick, carries your own permission level, can be revoked anytime, and refreshes automatically so you stay connected — no long-lived secret living on your machine.

Claude Desktop tip: if clicking Add shows "server URL already exists", fully restart the Claude desktop app — the connector will be in your list when it reopens. This is a known Claude Desktop quirk, not an Elixium error.

Claude Code can use the same hosted connector by adding it as a remote MCP server pointing at https://connect.elixium.ai/mcp. Prefer a local, key-based setup? Use the IDE extension and manual configs below.

🧩 IDE Coding Agents: Elixium AI Companion Extension

Install our VS Code extension and sign in— the default flow is sign in → pick board → done. No API key, no JSON editing, no local server process.

  1. Install Elixium AI Companion from the VS Code Marketplace (or sideload the .vsix for air-gapped environments)
  2. Click the Elixium icon in the activity bar and, in the Connect panel, click Sign in with Elixium
  3. Your browser opens Elixium's consent page — sign in and pick the workspace to connect
  4. Back in VS Code, pick your board — done. The extension writes a remote MCP entry your other agents can share.

What you get: an OAuth 2.1 session (PKCE, auto-refreshing, revocable) scoped to the workspace you picked, a credential-free {"type": "http"} entry in .vscode/mcp.json, correct config format per agent (servers vs mcpServers), and safe merge with your existing configs.

Self-hosted / air-gapped? Open Self-hosted deploymentin the Connect panel and enter your deployment's connect URL — sign-in routes to youridentity provider via the endpoint's discovery metadata, with the same steps as SaaS and no traffic leaving your network. Sideload the .vsix from your deployment package for fully offline installs.

Coming from the API-key setup? The legacy key-based flow (and the Elixium: Advanced Setup wizard) still works during the coexistence window. On activation the extension detects legacy configs and offersa one-click migration to the remote entry — it strips the API key from the file and preserves your board; declining leaves everything working as-is.

🏪 Alternative: VS Code MCP Gallery (legacy, key-based)

Elixium is available in the VS Code MCP Server Gallery — the same place you find GitHub, Notion, Playwright, and other MCP servers. The gallery installs the legacy key-based local server; if you can use the extension's sign-in flow above (or the remote entry below), prefer that — no API key required.

Option A: Install from VS Code

  1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  2. Type "MCP: Add Server" and select it
  3. Search for "elixium" in the gallery
  4. Click Install — VS Code will prompt you to enter the required environment variables (see below)

Option B: Install from the Web

  1. Visit the GitHub MCP Registry
  2. Search for "elixium"
  3. Click "Install in VS Code" — it opens VS Code with a pre-filled config and prompts for your variables

You'll be prompted for:

  • ELIXIUM_API_KEY — Your API key from Profile > your workspace card > Generate Key
  • ELIXIUM_API_URL — Your workspace URL, e.g. https://your-team.elixium.ai/api
  • ELIXIUM_BOARD_SLUG — (optional) The board to connect to, defaults to auto-detect
  • ELIXIUM_USER_EMAIL — (optional) Your email for story attribution

Why use the gallery? No npx, no JSON editing, no stdout issues. VS Code handles installation and lifecycle management for you. Updates are picked up automatically when new versions are published.

Generate Your API Key

What You Get

Once connected, the Elixium AI Companion adds these capabilities to your IDE:

Iteration Context Panel

A dedicated sidebar showing Current and Backlog stories with points, state, and objectives. Warm-starts from cache so your board is visible instantly. Click any story to open in the board or create a git branch.

Story Actions

Create stories, move between lanes, set states, start story flows, and copy implementation briefs — all from the Command Palette. Guardrails prevent accidental story advancement.

Real-Time Notifications

Background polling detects story changes every 60 seconds. Get notified when stories move lanes or change state without checking the board.

Multi-Agent Support

One setup wizard configures Copilot, Cursor, Claude Code, Codex, and Windsurf simultaneously. Each gets the correct config format with your credentials stored securely.

Manual Config (Without the Extension)

If you prefer editing JSON directly: the remote entry (next section) needs no credential at all — just the URL. The steps below are for the legacy key-based local server, which remains supported during the coexistence window:

  1. Get your API Key — Open the Elixium app and click your profile (top right) to open the Profiletab. Scroll to the Workspaces section, find the card for the workspace you want a key for, and clickGenerate Key. A confirmation prompt will appear; confirm, then copy the key immediately — it is only shown once and cannot be retrieved later. Paste it into your IDE config asELIXIUM_API_KEY. To rotate, clickGenerate Key again on the same workspace card — the old key is invalidated as soon as the new one is created.
  2. Find your Board Slug — Copy the slug from your board URL (e.g., my-project from elixium.ai/tenant/myteam/board/my-project).
  3. Configure your AI Agent — Add the MCP config to your IDE (see below).
  4. Verify— Ask your AI: "What stories are in Current?"

📦 Prerequisites

Remote connection (extension sign-in or the remote entry): nothing to install. The legacy local MCP server runs via npx (included with Node.js) — no separate installation required; it downloads automatically on first use.

Required: Node.js 18+

# Check if Node.js is installed

node --version

# If not installed, get it from nodejs.org or use:

brew install node # macOS

Optional: Pre-install the MCP Server

While npx auto-downloads on first run, you can pre-install globally for faster startup:

npm install -g @elixium.ai/mcp-server

If globally installed, change "command": "npx" to "command": "elixium-mcp" in your config.

💡 Tip: The configs below use npx -y @elixium.ai/mcp-server@latest which always fetches the latest version. This is the recommended approach.

🤖 Configuration by AI Agent

Using the Elixium AI Companion extension? The sign-in flow configures your agents automatically. The manual configs below are for reference or for environments without the extension.

✅ Current: the remote entry (no API key)

Agents with remote MCP support (Copilot on VS Code 1.102+, Claude Code, Cursor) connect with a single credential-free entry — the agent signs in via OAuth on first use:

{
  "servers": {
    "elixium": {
      "type": "http",
      "url": "https://connect.elixium.ai/mcp"
    }
  }
}

Copilot uses the servers root key; Claude Code / Cursor use mcpServers with the same entry. Self-hosted deployments substitute their own connect URL. The legacy stdio configs below (API key + local npx server) remain fully supported during the coexistence window.

🐙 GitHub Copilot (VS Code) — legacy key-based config

MCP support is GA as of VS Code 1.102 (July 2025). Copilot can now use Elixium tools natively.

Easiest: Use the VS Code MCP Galleryabove — search "elixium" and one-click install. The manual config below is for advanced setups.

Manual setup — create .vscode/mcp.json in your project:

{
  "servers": {
    "elixium": {
      "command": "npx",
      "args": ["-y", "@elixium.ai/mcp-server@latest"],
      "env": {
        "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
        "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
        "ELIXIUM_BOARD_SLUG": "main",
        "ELIXIUM_USER_EMAIL": "<YOUR_EMAIL>"
      }
    }
  }
}

Note: Copilot uses servers (not mcpServers).

✨ Gemini / Google Antigravity — legacy key-based config

Configure in your global or workspace MCP settings.

{
  "mcpServers": {
    "elixium": {
      "command": "npx",
      "args": ["-y", "@elixium.ai/mcp-server@latest"],
      "env": {
        "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
        "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
        "ELIXIUM_BOARD_SLUG": "main",
        "ELIXIUM_USER_EMAIL": "<YOUR_EMAIL>"
      }
    }
  }
}

🎯 Cursor — legacy key-based config

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "elixium": {
      "command": "npx",
      "args": ["-y", "@elixium.ai/mcp-server@latest"],
      "env": {
        "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
        "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
        "ELIXIUM_BOARD_SLUG": "main",
        "ELIXIUM_USER_EMAIL": "<YOUR_EMAIL>"
      }
    }
  }
}

🟠 Claude Desktop — legacy key-based config

Recommended: use the hosted connector at the top of this page (https://connect.elixium.ai/mcp) — OAuth sign-in, no API key. The local stdio config below is for offline / air-gapped setups or if you specifically want a key-based local server.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "elixium": {
      "command": "npx",
      "args": ["-y", "@elixium.ai/mcp-server@latest"],
      "env": {
        "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
        "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
        "ELIXIUM_BOARD_SLUG": "main",
        "ELIXIUM_USER_EMAIL": "<YOUR_EMAIL>"
      }
    }
  }
}

🟣 Claude Code (VS Code Extension) — legacy key-based config

Claude Code runs as a VS Code extension with full MCP support. Add the config to your project or user settings.

Option 1: Project-level — create .claude/settings.local.json in your project:

{
  "mcpServers": {
    "elixium": {
      "command": "npx",
      "args": ["-y", "@elixium.ai/mcp-server@latest"],
      "env": {
        "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
        "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
        "ELIXIUM_BOARD_SLUG": "main",
        "ELIXIUM_USER_EMAIL": "<YOUR_EMAIL>"
      }
    }
  }
}

Option 2: User-level — add to ~/.claude/settings.json to share across all projects:

{
  "mcpServers": {
    "elixium": {
      "command": "npx",
      "args": ["-y", "@elixium.ai/mcp-server@latest"],
      "env": {
        "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
        "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
        "ELIXIUM_BOARD_SLUG": "main",
        "ELIXIUM_USER_EMAIL": "<YOUR_EMAIL>"
      }
    }
  }
}

💡 Tip: Use .claude/settings.local.json (not settings.json) for project-level config — the .local variant is gitignored by default, keeping your API key out of source control.

⚠️ Watch out for duplicate config files: Claude Code can also read MCP config from a .mcp.json file in your project root. If both .mcp.json and .claude/settings.local.json exist, .mcp.json takes precedence. If you regenerate your API key, make sure to update all config files — a stale key in .mcp.json will silently override your updated key in .claude/settings.local.json, causing "Invalid API Key" errors even though the new key looks correct. We recommend using only one config file to avoid this issue.

⌨️ OpenAI Codex CLI — legacy key-based config

Create .codex/mcp.json in your project:

{
  "mcpServers": {
    "elixium": {
      "command": "npx",
      "args": ["-y", "@elixium.ai/mcp-server@latest"],
      "env": {
        "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
        "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
        "ELIXIUM_BOARD_SLUG": "main",
        "ELIXIUM_USER_EMAIL": "<YOUR_EMAIL>"
      }
    }
  }
}

⚙️ Environment Variables (legacy local server)

The legacy stdio server is configured with these environment variables (the remote entry needs none of them):

VariableRequiredDescription
ELIXIUM_API_KEYYesYour workspace API key from Settings
ELIXIUM_API_URLYesYour tenant API URL (e.g., https://acme.elixium.ai/api)
ELIXIUM_BOARD_SLUGRecommendedBoard slug to connect to (defaults to main)
ELIXIUM_USER_EMAILOptionalYour email address. Used as the "Requested by" field when creating stories via AI. If not set, defaults to the API key owner's email.

💡 Tip: Setting ELIXIUM_USER_EMAIL ensures stories you create through your AI assistant are attributed to you, not the workspace API key owner.

🛠️ Available MCP Tools

Once connected, your AI agent can use these tools:

list_stories

List all stories on the board

get_iteration_context

Get Current + Backlog for planning

create_story

Create a new story with AC

update_story

Update story state, lane, or description

prepare_implementation

Fetch full context for a story

record_learning

Log what you learned from a story

list_epics

List all epics on the roadmap

list_objectives

List workspace objectives (OKRs)

📋 Teaching Your AI Agent

Add a rules file to your repo so the AI knows how to use Elixium effectively. The Setup Wizard can also scaffold Claude slash commands (.claude/commands/) for common workflows like starting stories and checking board status.

Rules File Locations

  • GitHub Copilot: .github/copilot-instructions.md
  • Cursor: .cursor/rules/elixium.md
  • Windsurf: .windsurf/rules/elixium.md
  • Claude Code: CLAUDE.md at repo root
  • Codex CLI: AGENTS.md at repo root

Sample Rules Content

# Elixium Integration

At the start of each session:
1. Call `get_iteration_context` to load the board
2. Review Current lane for active work

When implementing a story:
1. Call `prepare_implementation` for full context
2. Follow TDD: write tests first
3. Update story state to "started"
4. Commit with story ID in message

When complete:
1. Update story state to "finished"
2. Call `record_learning` with outcomes

🔄 Built-in Workflows

Initialize ready-to-use workflows in your project:

# Initialize Elixium workflows

npx @elixium.ai/mcp-server init

This creates .agent/workflows/ with:

  • load-board-context.md — Load board at session start
  • implement-story.md — Full story implementation flow
  • manage-board.md — Create/update stories and epics

🔐 Security

Hosted Connection: OAuth 2.1 (recommended)

The sign-in flow puts no long-lived secret in any file: sessions use short-lived access tokens with rotating refresh tokens (reuse revokes the whole chain), are scoped to the one workspace you pick with your own permission level, and can be revoked anytime. See API & MCP Security for the full surface.

Tenant-Scoped API Keys (legacy path)

Each API key is hardcoded to your workspace. Even if a key is compromised, it only provides access to your specific projects. Keys can be rotated or revoked at any time from workspace settings.

Best Practice: Use environment variables or a secrets manager instead of hardcoding keys in config files. Add .vscode/mcp.json and.cursor/mcp.json to your .gitignore. Claude Code's .claude/settings.local.json is gitignored by default.
Elixium AI Companion: The Setup Wizard stores your credentials in the OS keychain via VS Code SecretStorage and automatically adds secret-containing config files to .gitignore. Credentials are pre-filled on subsequent runs without being stored in plaintext on disk.

🔧 Troubleshooting

Quick Diagnostic Checklist

  1. Restart your IDE / agent — MCP servers are loaded at startup. After changing config, you must fully restart (not just reload the window). For Claude Code: exit with Ctrl+C or /exit, then relaunch.
  2. Test the command in your terminal first — Run the server manually to check for errors:
    npx -y @elixium.ai/mcp-server@latest
    If this fails or hangs, your IDE won't be able to start it either.
  3. Verify Node.js is available — The MCP server requires Node.js 18+:
    node --version # Should be v18+
  4. Check the config key name — GitHub Copilot uses "servers", all others use "mcpServers". Using the wrong key silently fails.
  5. Verify your API key — Go to your workspace Command Center (Profile tab) and confirm the key is active and not revoked.

Common Errors

"Invalid API Key" or "401 Unauthorized"

  • Double-check the key — copy/paste from Command Center, don't type it manually
  • Make sure ELIXIUM_API_URL includes your tenant subdomain (e.g., https://my-team.elixium.ai/api, not https://elixium.ai/api)
  • Check the key hasn't been revoked in workspace settings
  • Check for duplicate config files — If you have both .mcp.json (project root) and .claude/settings.local.json, the .mcp.json file takes precedence. A stale key in .mcp.json will override your updated key. Run cat /proc/$(pgrep -f elixium-mcp)/environ | tr '\0' '\n' | grep ELIXIUM_API_KEY to verify which key the running server is actually using.
  • Fully quit your IDE — A window reload may not restart the MCP server process. Quit completely and reopen to pick up config changes.

"Board not found"

  • Confirm ELIXIUM_BOARD_SLUG matches your board URL exactly (case-sensitive)
  • Default slug is main — check your board URL to verify

"Connection closed" or "Failed to parse message"

  • npx stdout pollution (most common):When npx downloads the package for the first time, it prints installation output ("changed 38 packages...") to stdout. MCP uses stdout for JSON-RPC, so the IDE can't parse it and the connection drops. Fix: pre-install globally so npx has nothing to download:

    # Install once

    npm install -g @elixium.ai/mcp-server

    Then update your config to use the installed binary:
    "command": "elixium-mcp", "args": []
  • Version managers (asdf, nvm, fnm): These can print reshimming or version-switch messages to stdout/stderr when npx runs, causing the same parse failure. The global install fix above avoids this.
  • Windows users: You must wrap npx with cmd /c:
    "command": "cmd", "args": ["/c", "npx", "-y", "@elixium.ai/mcp-server@latest"]
  • If npx isn't found, use the full path: which npx (macOS/Linux) or where npx (Windows) to find it
  • Corporate proxies can block npx downloads — the global install with npm install -g @elixium.ai/mcp-server also fixes this

Tools not appearing after connection

  • The server may be connected but the env vars are missing — check all 4 env vars are set in the env block
  • Try asking your AI: "What MCP tools are available?" to see if Elixium tools are listed

IDE-Specific Diagnostics

🟣 Claude Code

  • Run /mcp to see all server connection statuses
  • Run /doctor to validate config files and diagnose errors
  • Config files: .claude/settings.local.json (project) or ~/.claude/settings.json (user)
  • Config precedence: If a .mcp.json file exists in your project root, it takes priority over .claude/settings.local.json. Use only one to avoid stale-key issues when regenerating API keys.
  • After changing config, fully quit VS Code (not just reload window) — the MCP server process may persist across reloads with the old environment variables.

🐙 GitHub Copilot (VS Code)

  • Open Output panel → select "GitHub Copilot" channel for MCP logs
  • Check .vscode/mcp.json uses "servers" (not "mcpServers")
  • Requires VS Code 1.102+ and Copilot extension

🎯 Cursor

  • Go to Settings → MCP to see connected servers and connection status
  • Config file: .cursor/mcp.json in project root
  • Restart Cursor completely after config changes (not just reload)

Still stuck? If none of the above helps, check that the config JSON is valid (no trailing commas, correct brackets). You can validate it by pasting into jsonlint.com or running cat your-config.json | python3 -m json.tool.

Need Help?

Book a quick call with our team to get set up.

📅 Book a 30-min Demo