Elixium Logo
elixium.aiHuman + AI Agile

IDE Integration

Connect Elixium to your AI coding assistant. Access your backlog, update stories, and get AI guidance without leaving 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.

🚀 Fastest: Elixium AI Companion Extension

Install our VS Code extension and run the Setup Wizard— it configures Copilot, Cursor, Claude Code, Codex, and Windsurf automatically. No JSON editing required.

  1. Install Elixium AI Companion from the VS Code Marketplace (or sideload the .vsix for air-gapped environments)
  2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run "Elixium: Setup Wizard"
  3. Enter your API URL, API Key, and email — click Validate
  4. Select your boards and choose which AI agents to configure
  5. Click Configure — done!

What the wizard handles for you: correct config format per agent (servers vs mcpServers), safe merge with your existing configs, OS keychain credential storage, .gitignore protection for secret-containing files, multi-board support, and optional Claude slash command scaffolding.

Air-gapped / offline? The extension works fully offline. Your deployment package includes the .vsixfile — sideload it in VS Code and the wizard configures everything against your internal Elixium instance.

🏪 Alternative: VS Code MCP Gallery

Elixium is available in the VS Code MCP Server Gallery — the same place you find GitHub, Notion, Playwright, and other MCP servers. This is the easiest way to get started with GitHub Copilot or any VS Code AI agent.

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, or for environments where you can't install the extension:

  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

The Elixium MCP server runs via npx (included with Node.js). No separate installation is 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 Setup Wizard configures all of these agents automatically. The manual configs below are for reference or for environments without the extension.

🐙 GitHub Copilot (VS Code)

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

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

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

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)

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

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

Configure the MCP server using these environment variables:

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

Tenant-Scoped API Keys

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