Elixium MCP Server

This server implements the Model Context Protocol (MCP), allowing AI agents (like Antigravity, Cursor, or Windsurf) to interact directly with your Elixium Board.

Features

• List Stories: See the current backlog and icebox.
• Create Story: Add new stories directly from your editor.
• Update Story: Move stories between lanes and update fields.
• Iteration Context: Provide the AI with the full context of your Current and Backlog lanes for better planning.

Quick Start

1. Install (Optional)

If you want to install the package locally:

npm install -D @elixium.ai/mcp-server@latest

Or install globally:

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

[!TIP] You can also use npx to run the server without installing it (recommended for IDE configurations).

2. Get Your API Key

Contact your Elixium workspace administrator to obtain an API key for your tenant.

3. Configure Your IDE

Add the following to your IDE's MCP configuration file (e.g., mcp_config.json):

{
  "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>"
      }
    }
  }
}

Replace:

• <YOUR_API_KEY> with the API key from your administrator
• <YOUR_TENANT> with your workspace subdomain (e.g., acme for acme.elixium.ai)
• <YOUR_EMAIL> with your email address (used as the "requester" on stories you create)

[!NOTE] Different IDEs and MCP clients expect different top-level keys and file paths. Use the setup that matches your IDE:

• VS Code + Elixium Companion: .vscode/mcp.json with mcpServers
• Cursor: .cursor/mcp.json with mcpServers
• Cline (VS Code extension): cline_mcp_settings.json with mcpServers
• Continue: .continue/config.yaml (or .continue/mcpServers/*.json) with mcpServers
• VS Code native MCP: .vscode/mcp.json with servers

Shared Daemon (SSE)

If you want a single MCP server shared by multiple clients (VS Code, Codex, etc), run the server in SSE mode and point each client to the same url.

Start the daemon:

elixium-mcp-server --sse --host 127.0.0.1 --port 7357

Client config example:

{
  "mcpServers": {
    "elixium": {
      "transport": "sse",
      "url": "http://127.0.0.1:7357/sse"
    }
  }
}

For VS Code auto-start and multi-client setup, see docs/ide/README.md.

Multi-MCP Example (Stripe + Elixium)

If you're using multiple MCP servers, combine them in the same config:

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp", "--tools=all", "--api-key=<STRIPE_KEY>"],
      "env": {}
    },
    "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"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ELIXIUM_API_KEY | ✅ Yes | Your tenant-scoped API key | | ELIXIUM_API_URL | ✅ Yes | Your tenant's API endpoint (e.g., https://acme.elixium.ai/api) | | ELIXIUM_BOARD_SLUG | ⚠️ Recommended | Board slug to scope operations (e.g., main) | | ELIXIUM_USER_EMAIL | Optional | Your email address. Sets the "Requested by" field when creating stories. Defaults to API key owner. | | ELIXIUM_LANE_STYLE | Optional | upper for BACKLOG/CURRENT or title for Backlog/Current (auto-detected) |

[!IMPORTANT] If you set ELIXIUM_BOARD_SLUG, the MCP server will only read/write stories for that board. The server resolves the board slug to a boardId on startup, so the slug must match an existing board.

Usage

Once configured, your AI agent will have access to tools like:

• list_stories - View all stories on the board
• create_story - Add new stories with title, description, lane, and points
• update_story - Move stories between lanes or update fields
• list_epics - View epics on the board
• get_iteration_context - Get current iteration and backlog for planning

TDD Workflow Tools

These tools enforce Test-Driven Development for AI agents:

• start_story - Start TDD workflow: creates branch, sets workflow_stage to tdd_start
• propose_test_plan - Submit test plan for human review (BLOCKS implementation)
• submit_for_review - Submit implementation for human review (requires approved tests)

See the TDD Workflow Guide for the complete workflow.

[!NOTE] Many MCP clients namespace tools by server name. If your MCP config uses the server key "elixium", Codex will typically expose these tools as mcp_elixium_list_stories, mcp_elixium_get_iteration_context, etc.

Initialize Agent Workflows

New projects can scaffold the agent workflow documentation with:

npx @elixium.ai/mcp-server init

This creates .agent/workflows/ with:

• implement-story.md - TDD implementation workflow
• manage-board.md - Board management commands
• load-board-context.md - Session context loading

If you already have workflows and want to restore the originals:

rm -rf .agent/workflows
npx @elixium.ai/mcp-server init

Development (Source Build)

If you're contributing or developing from source:

cd mcp-server
npm install
npm run build

To use the local build, update your config:

{
  "elixium": {
    "command": "node",
    "args": ["/path/to/mcp-server/dist/index.js"],
    "env": { ... }
  }
}

Maintainers: Release Process

cd mcp-server
npm install
npm run build
npm version patch  # or minor/major
npm publish --access public