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.
• Board Context (new in 0.6.0): One-call grounding tool (get_board_context) that returns a time-balanced workspace snapshot — in-flight work, queued/icebox/recently-completed stories and epics, recent decisions, objectives, learnings, and workspace configuration — so agents ground themselves before drafting or updating content. Requires a backend release that includes GET /api/board-context (SaaS: live since 2026-05-17; self-hosted: update to a matching release). Falls back gracefully with a usable message if the backend is older.
• Per-blocker mutations (new in 0.7.0): Declare structural dependencies between stories during grooming via add_blocker (storyId + blockerStoryId + reason) and remove_blocker (storyId + blockerStoryId). Per-element mutation eliminates the fetch-modify-write race a full-array PATCH would re-introduce. Each mutation emits a typed audit_log row (story.blocker_added / story.blocker_removed) so structural dependencies carry the same attestation discipline as test approvals. Backend resolves the blocker's title authoritatively from its row at write-time — callers don't supply it. Requires a backend release that includes POST /api/stories/:id/blocked_by + DELETE /api/stories/:id/blocked_by/:blockerStoryId (SaaS: live since 2026-05-18; self-hosted: update to a matching release).
• Per-role Three-Amigos attestations (new in 0.8.0): update_three_amigos_check (storyId + role + value) writes a single role's signoff atomically via jsonb_set, eliminating the fetch-modify-write race a full-object PATCH would re-introduce. Each mutation emits a typed three_amigos.attested audit_log row with the role and value in details. Requires a backend release that includes PATCH /api/stories/:id/three_amigos_checks/:role (SaaS: live since 2026-05-19; self-hosted: update to a matching release). Gated per-workspace by the balancedTeam feature flag — when off, the discipline is opt-out and no MCP read surface renders it.
• Read-path coherence in prepare_implementation (new in 0.8.0): The implementation brief now surfaces what writes have landed — ## Blocked By renders when story.blocked_by is a non-empty array (paired with add_blocker / remove_blocker from 0.7.0); ## Three-Amigos Readiness renders the per-role attestation state with a count summary, gated on the workspace's balancedTeam flag (paired with update_three_amigos_check). Honors the Read-Path Coherence discipline — write surfaces ship paired with read surfaces in the same release wave so agents reading the brief always see what other agents wrote.
• Read-path coherence in start_story and get_board_context (new in 0.9.0): The start_story response now carries the same ## Blocked By + ## Three-Amigos Readiness sections that v0.8.0 added to prepare_implementation, so agents walking the TDD flow encounter structural state at every grounding moment, not just at implementation time. get_board_context.inFlight.stories[] entries now carry threeAmigosChecks (full per-role object) + attestedSummary (scannable single-line string with 8 canonical states from a formatAttestationSummary helper) on every entry — explicit null on workspaces with balancedTeam: false for wire-shape consistency with the v0.8.0 backend response pattern. Requires a backend release that includes the POST /api/stories/:id/start response extension + the boardContext.ts CTE projection + composer changes (SaaS: live since 2026-05-19; self-hosted: update to a matching release).
• Methodology-aware response shaping — hypothesis-driven shape in start_story (new in 0.10.0): First instantiation of the participation thesis — start_story now renders a ## Hypothesis Check section on workspaces with teamProfile.developmentApproach: 'hypothesis-driven', framing the implementation around validating the hypothesis (not just rendering the field). Two variants: hypothesis-present (with "moves the hypothesis from belief to evidence" + 3 ordered bullets) and hypothesis-missing (⚠️ MISSING warning with explicit exception phrasing for spike / refactor / non-falsifiable-claim prerequisite work). New acknowledge_no_hypothesis: true + acknowledge_no_hypothesis_reason: string (≥20 chars) override flag on start_story for legitimate exceptions; acknowledgment emits a typed participation.hypothesis_acknowledged_absent audit_log row (distinct namespace from gates_bypassed.* — methodology overrides are not compliance bypasses). Other 5 developmentApproach enum values (continuous-delivery, tdd, scrum, kanban, other) fall through to default behavior in v1; future shapes for these methodologies follow under the same services/methodologyShaping.ts registry. Backend renders the section; mcp-server consumes the pre-rendered string adjacent to existing sections (matches d778a968's package boundary precedent). Requires a backend release that includes the methodology shaping registry + start endpoint extension (SaaS: live since 2026-05-19; self-hosted: update to a matching release).
• Tool-topology gate for update_three_amigos_check (new in 0.11.0): The update_three_amigos_check tool is now structurally absent from the ListTools response on workspaces with balancedTeam: false — closing the v0.8.0 reviewer-found gap where the tool could be successfully called on non-opt-in workspaces with no warning, no refusal, no audit annotation. Implementation follows the codebase's established house pattern for workspace-opt-in tools: a new balancedTeamTools conditional array gated at MCP registration time, mirroring the four prior conditional arrays (tddTools, learningLoopTools, teamDecisionsTools, ragTools). Level-4 affordance applied via consistency with the established house pattern, not deliberate escalation from the reviewer's level 2/3 suggestion. Read-surface gating (section rendering in prepare_implementation / start_story handlers) preserved and operative as a separate layer; both gates run independently. Workspaces with balancedTeam: true see the tool exposed and operating exactly as before; workspaces with balancedTeam: false or undefined don't see it at all. No backend changes required — the balancedTeam flag was already exposed in GET /config/features; this release is mcp-server-only.

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.

Required Scopes (for Scoped API Keys)

If you generate a scoped API key (via the Command Center → Integrations → Advanced: Key Scopes), the key must include the scopes below to use the corresponding MCP tools. An unscoped key (all scopes picker collapsed when generating) has full access and works with every tool.

| Tool category | Tools | Required scopes | |---|---|---| | Read stories | list_stories, get_story, get_iteration_context, prepare_implementation, estimate_cost | stories:read | | Write stories | create_story, update_story, start_story, propose_test_plan, submit_for_review, record_learning, create_hypothesis | stories:read + stories:write | | Read epics | list_epics, get_epic_cost_rollup | epics:read | | Write epics | create_epic, update_epic, prioritize_epic | epics:read + epics:write | | Read boards | list_boards, select_board | boards:read | | Write boards | create_board | boards:read + boards:write | | Read workspace config | get_feature_config, get_infrastructure_profile | workspace:read | | Team decisions | list_decisions, search_decisions | stories:read | | Team decisions (write) | record_decision | stories:read + stories:write | | Objectives | list_objectives | stories:read |

Recommended baseline for full MCP functionality:

stories:read, stories:write, epics:read, epics:write, boards:read, workspace:read

If a scoped key is missing a scope, the MCP server surfaces an actionable error message naming the missing scope and directing you to regenerate the key with the required scope. You do NOT need to restart the MCP server after regenerating — just update ELIXIUM_API_KEY in your config and reload the server.

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