MCP Setup Guide

This guide walks you through setting up the LumenFlow MCP server with your AI coding assistant.

What is MCP?

MCP (Model Context Protocol) is an open standard for AI-to-tool communication. Instead of relying on file-based instructions, MCP provides a programmatic interface for AI assistants to interact with development tools.

Structured Tools

Tools with typed inputs and outputs, not just text parsing

Resource Access

Direct access to LumenFlow data via URI patterns

Consistent Interface

Same tools work across different AI clients

Safety Maintained

All operations respect LumenFlow workflow rules

Prerequisites

Before setting up MCP:

1. LumenFlow initialized in your project

   pnpm lumenflow

2. AI client with MCP support

   • Claude Code 0.2.x+
   • Cursor (MCP-enabled)
   • Any MCP-compatible client

Tip

MCP is optional. LumenFlow works with any AI through markdown files (AGENTS.md, LUMENFLOW.md). MCP provides enhanced programmatic access for supported clients.

Installation

1. Install the MCP package (if not already included)

   pnpm add -D @lumenflow/mcp

2. Verify the binary is available

   npx @lumenflow/mcp --help

Client Configuration

Claude Code

Claude Code Setup

Claude Code supports MCP servers via configuration files.

Option 1: Project-level configuration

Create or edit .claude/mcp.json:

{
  "mcpServers": {
    "lumenflow": {
      "command": "npx",
      "args": ["@lumenflow/mcp"],
      "env": {
        "LUMENFLOW_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Option 2: Global configuration

Add to your Claude Code settings (~/.config/claude/mcp.json on Linux, ~/Library/Application Support/claude/mcp.json on macOS):

{
  "mcpServers": {
    "lumenflow": {
      "command": "npx",
      "args": ["@lumenflow/mcp"]
    }
  }
}

Note

With global configuration, LUMENFLOW_PROJECT_ROOT defaults to process.cwd(). The server auto-detects the project root from the current working directory.

Verify the connection:

In Claude Code, the LumenFlow tools should appear in the available tools list:

• context_get
• wu_list
• wu_status
• wu_create
• wu_claim
• wu_done
• gates_run
• file_read
• git_status
• plan_create
• signal_cleanup
• wu_proto

The full MCP surface is documented in /reference/mcp and currently includes 114 registered tools (107 in allTools plus 7 runtime task tools).

Cursor

Cursor Setup

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "lumenflow": {
      "command": "npx",
      "args": ["@lumenflow/mcp"],
      "env": {
        "LUMENFLOW_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Other Clients

Generic MCP Client

For any MCP-compatible client, configure:

| Setting | Value | | --------- | -------------------- | | Command | npx | | Arguments | ["@lumenflow/mcp"] |

Environment variables:

| Variable | Description | Default | | ------------------------- | ---------------------- | --------------- | | LUMENFLOW_PROJECT_ROOT | Project root directory | process.cwd() | | LUMENFLOW_MCP_LOG_LEVEL | Log level | info |

Remote Streamable HTTP

The examples above use stdio, which remains the default. Stdio is a local process-environment trust boundary and does not use the HTTP bearer flow.

For a shared long-lived service, select Streamable HTTP and configure the exact remote trust binding:

LUMENFLOW_MCP_TRANSPORT=http \
LUMENFLOW_MCP_HTTP_ISSUER=https://issuer.example.com \
LUMENFLOW_MCP_HTTP_RESOURCE=https://runtime.example.com/mcp \
LUMENFLOW_MCP_HTTP_WORKSPACE_ID=workspace-1 \
LUMENFLOW_CONTROL_PLANE_SIGNING_KEY=replace-with-a-strong-secret \
  npx @lumenflow/mcp

| Variable | Purpose | | ------------------------------------- | ---------------------------------------------------- | | LUMENFLOW_MCP_HTTP_ISSUER | Exact trusted credential issuer | | LUMENFLOW_MCP_HTTP_RESOURCE | Exact protected resource URL and credential audience | | LUMENFLOW_MCP_HTTP_WORKSPACE_ID | Exact workspace accepted by this MCP deployment | | LUMENFLOW_CONTROL_PLANE_SIGNING_KEY | Secret used to verify signed remote credentials | | LUMENFLOW_MCP_HTTP_HOST | Bind host; defaults to 127.0.0.1 | | LUMENFLOW_MCP_HTTP_PORT | Bind port; defaults to 8848 |

Every MCP protocol request must send a signed Authorization: Bearer … credential. Verification requires a valid signature and expiry, the configured issuer, exact resource audience and workspace, and a canonical subject. Opaque bearer fallback is off. Legacy tool scopes do not become transport permissions.

The supported transport permissions are:

• task:read and task:write
• event:read and evidence:read
• discovery:read
• tool:invoke
• ag-ui:run

Authentication occurs before URL parsing, body reads, session lookup, or MCP server creation. Invalid credentials receive 401 invalid_token; an authenticated caller without the operation permission receives 403 insufficient_scope.

The server never forwards the bearer to tools, the kernel, logs, evidence, or session state. It stores only the sanitized principal, workspace, resource, and permission set. Every Mcp-Session-Id is bound to that exact context; a later request that changes the principal, workspace, resource, or permissions is rejected. Successful transport admission does not bypass downstream kernel ownership, scope, policy, approval, or evidence checks.

The protected-resource metadata endpoint is the public RFC 9728 exception. It is derived from the resource URL: for https://runtime.example.com/mcp, use https://runtime.example.com/.well-known/oauth-protected-resource/mcp. All other MCP HTTP routes require authentication.

Caution

Remote request fields never grant kernel authority. Do not add principal, workspace, scopes, ownership, session, or policy fields to a tool body. Task identity, ownership, claim identity, session IDs, and run IDs are derived from authenticated and persisted server state.

Web runtime migration

The web HTTP surface uses the same signed credential and permission model, but its deployment variables are:

LUMENFLOW_WEB_HTTP_ISSUER=https://issuer.example.com
LUMENFLOW_WEB_HTTP_RESOURCE=https://runtime.example.com
LUMENFLOW_CONTROL_PLANE_SIGNING_KEY=replace-with-a-strong-secret

The web runtime reads the exact workspace ID from workspace.yaml. GET /api/health without a credential is intentionally public but returns only { "success": true, "status": "ok" }. Presenting a credential opts into authentication: an invalid credential is rejected, and detailed diagnostics are returned only after successful authentication.

Using MCP Tools

Once configured, your AI assistant can use LumenFlow tools directly.

Tip

If you are validating parity coverage specifically, spot-check at least one tool from each added wave-2 family (for example: file_read, git_status, plan_create, signal_cleanup, wu_proto).

Example Workflow

User: Create a WU for adding authentication

AI uses: wu_create {
  "lane": "Framework: Core",
  "title": "Add user authentication",
  "description": "Context: No auth. Problem: Users cannot log in. Solution: Add auth.",
  "acceptance": ["Users can register", "Users can log in"],
  "code_paths": ["src/auth/"],
  "exposure": "backend-only"
}

AI: Created WU-123. Would you like me to claim it?

User: Yes, claim it

AI uses: wu_claim {
  "id": "WU-123",
  "lane": "Framework: Core"
}

AI: WU-123 claimed. Worktree created at worktrees/framework-core-wu-123.

Checking Context

The AI can check current context at any time:

AI uses: context_get {}

Result: {
  "location": { "type": "worktree", ... },
  "wu": { "id": "WU-123", "status": "in_progress" }
}

Reading Resources

AI assistants can read LumenFlow data via resources:

Read resource: lumenflow://backlog
Read resource: lumenflow://wu/WU-123
Read resource: lumenflow://context

MCP vs CLI vs File-Based

| Approach | Best For | When to Use | | ---------- | --------------------------- | ----------------------------- | | MCP | Programmatic AI interaction | AI clients with MCP support | | CLI | Human operators, scripts | Terminal workflows, CI/CD | | File-based | Universal AI compatibility | Any AI that can read markdown |

Tip

All three approaches work together. An AI can read LUMENFLOW.md for context, use MCP tools for operations, and fall back to CLI commands when needed.

Troubleshooting

Server not starting

Check: Is the package installed?

pnpm list @lumenflow/mcp

Check: Can you run it directly?

npx @lumenflow/mcp --help

Tools not appearing

Check: Is MCP enabled in your AI client?

Check: Is the configuration file in the correct location?

Check: Are there any errors in the AI client logs?

Wrong project root

Check: Is LUMENFLOW_PROJECT_ROOT set correctly?

Fix: Use explicit path or ensure the AI client is opened in the project directory.

Permission errors

Check: Does the user running the AI client have access to the project?

Check: Are all LumenFlow files readable?

Security Considerations

The MCP server:

• Runs with the permissions of the user starting the AI client
• Only accesses files within the project root
• Respects all LumenFlow workflow rules (worktree discipline, gates)
• Cannot bypass safety hooks or constraints
• Authenticates remote HTTP before route, body, session, or state work
• Separates transport permissions from kernel tool scopes
• Never treats request-body authority fields as caller identity
• Never passes a remote bearer credential into the kernel or evidence

Caution

MCP tools execute real operations. wu_done will merge and stamp. Ensure your AI client handles tool confirmations appropriately.

Advanced Configuration

Programmatic Server Creation

For custom integrations:

import { createMcpServer } from '@lumenflow/mcp';

const server = createMcpServer({
  projectRoot: '/path/to/project',
  logLevel: 'debug',
});

// List tools
console.log(server.listTools());

// List resources
console.log(server.listResources());
console.log(server.listResourceTemplates());

// Start the server
await server.start();

Custom Tool Timeout

Gates can take longer to run. The default timeout for gates_run is 10 minutes. This is configured in the tool implementation and cannot be overridden via MCP.

Next Steps

• MCP Reference - Complete tool and resource documentation
• CLI Commands - Full CLI reference
• AI Integrations - Other integration options