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. An agent host with MCP support

Tip

MCP is optional. LUMENFLOW.md remains the universal agent contract. MCP adds programmatic access when the current host supports it.

Installation

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

   pnpm add -D @hellmai/lumenflow-mcp

2. Verify the binary is available

   pnpm list @hellmai/lumenflow-mcp

Project-Owned Host Configuration

Follow your host’s current MCP documentation and register this server in the project-owned configuration:

Setting	Value
Command	pnpm
Arguments	["exec", "lumenflow-mcp"]

Environment variables:

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

LumenFlow does not create, update, validate, or version a host-specific MCP configuration file. LUMENFLOW_PROJECT_ROOT defaults to process.cwd() when omitted.

After registration, verify the mode-aware surface. Local stdio exposes applied in-process reads such as context_get, wu_list, and agent_resolve, plus the canonical methodology resources below. Authenticated HTTP adds task lifecycle and tool execution only when the bearer has the matching permission. The exact effective catalog is generated at /reference/mcp.

Caution

A registered handler is not automatically callable. Shell wrappers and unbound pack handlers are hidden as typed runtime_migration_pending exclusions until a governed runtime exists.

Protocol compatibility

LumenFlow serves the stable MCP 2026-07-28 revision. Its own clients and release certification pin that exact revision and fail closed when a peer offers only an older one. Both stdio and HTTP reject legacy openings. The underlying SDK can be configured explicitly for legacy interoperability by a downstream integrator, but that connection is non-certifying.

Modern clients use server/discover; there is no initialize/initialized exchange and no Mcp-Session-Id. Every request repeats its protocol revision, client capabilities, and optional client information in _meta. HTTP requests also carry MCP-Protocol-Version, Mcp-Method, and, where applicable, Mcp-Name.

LumenFlow advertises tools and resources. It currently advertises no list-change capability; if one is added, the current subscription method is subscriptions/listen. LumenFlow’s task_* names are ordinary tools and do not advertise the separate io.modelcontextprotocol/tasks extension.

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 \
  pnpm exec 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 MCP route selection, body reads, protocol handling, 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 protocol state. Each request receives only the sanitized principal, workspace, resource, and permission set and creates a fresh server instance. 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).

Mode-aware examples

Local stdio:
AI uses: context_get {}
AI uses: agent_resolve { "wu": "WU-123", "client": "codex-cli" }

Authenticated HTTP with task:read:
AI uses: task_inspect { "task_id": "WU-123" }

agent_resolve is planner-only. It reports requested/resolved routing and explicitly marks host application unattested; it never claims that a host applied a model or reasoning setting.

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 canonical methodology evidence via resources:

Read resource: lumenflow://methodology/contract
Read resource: lumenflow://methodology/skills
Read resource: lumenflow://methodology/skills/design-first

Each result includes canonical path/version and SHA-256 digest evidence. An individual skill URI can include ?digest=sha256:... to reject stale content. Reads are confined to the project contract and methodology skill roots; traversal and symlink escapes fail closed. Caller memory and synthetic briefs remain advisory and cannot elevate authority.

lumenflow://wu/{id} is available over authenticated HTTP with task:read. The legacy lumenflow://context and lumenflow://backlog resources remain hidden typed exclusions while their runtime migration is pending.

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. LUMENFLOW.md and canonical skill files remain authoritative; host memory is advisory. Use the generated semantic catalog to determine which MCP operations are actually callable, and use the CLI for local lifecycle commands that remain typed MCP exclusions.

Troubleshooting

Server not starting

Check: Is the package installed?

pnpm list @hellmai/lumenflow-mcp

Check: Can you start the installed binary? A healthy stdio server waits for an MCP client; stop the manual process after confirming it stays running without a discovery error.

pnpm exec lumenflow-mcp

Tools not appearing

Check: Is MCP enabled in your AI client?

Check: Does the project-owned host configuration use the command and arguments above?

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:

• Lists only capabilities callable under the current transport/auth mode
• Confines canonical methodology resource reads to project-owned roots
• Respects all LumenFlow workflow rules (worktree discipline, gates)
• Cannot bypass safety hooks or constraints
• Authenticates remote HTTP before MCP route, body, protocol, 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

Authenticated MCP task and tool operations execute real work and retain kernel policy/approval checks. Ensure your AI client handles confirmations appropriately.

Advanced Configuration

Programmatic Server Creation

For custom integrations:

import { createMcpServer } from '@hellmai/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
• Connect an AI Coding Assistant - Contract discovery guidance