Skip to the content.

MCP

Step by step, from setup to a delivered project: howto-mcp-project.md.

Overview

The orchestrator currently exposes a read-only MCP server based on FastMCP.

Relevant file:

Mount logic:

Current MCP characteristics

The current MCP server should be documented as:

What MCP is intentionally not

The current code explicitly excludes:

This restriction is important and should remain explicit in official docs.

BMAD-aware methodology profiles do not change this boundary. Future MCP write tools are documented only as roadmap material in docs/integrations/bmad/FUTURE_MCP_WRITE_TOOLS.md.

Current exposed MCP tools

Current tool inventory from mcp_server.py:

Capability and health

Catalog and routing

Product / workflow explanation

Harper docs and plan state

RAG

Run artifacts

Operating model

Authentication

The orchestrator MCP endpoint is protected by the service token like every orchestrator endpoint. It uses streamable HTTP semantics, so manual calls need both content-type and accept headers (otherwise HTTP 406); without the token the response is 401.

curl -s http://127.0.0.1:8080/mcp/ \
  -H "authorization: Bearer $CLIKE_API_TOKEN" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | jq

Registering it in an MCP client:

The token must reach the client as a header. With Claude Code, prefer a project .mcp.json that reads it from the environment (safe to commit: no secret inside) and export CLIKE_API_TOKEN in your shell before starting claude:

{
  "mcpServers": {
    "clike": {
      "type": "http",
      "url": "http://localhost:8080/mcp/",
      "headers": { "Authorization": "Bearer ${CLIKE_API_TOKEN}" }
    }
  }
}

claude mcp add --transport http clike http://localhost:8080/mcp/ --header "Authorization: Bearer $CLIKE_API_TOKEN" also works, but the shell expands the token when you add the server: with the variable unset it stores an empty bearer, otherwise it writes the token into ~/.claude.json. Use localhost, not 127.0.0.1 (managed policies often allow only http://localhost*), and keep the trailing /.

“Dynamic Client Registration rejected (HTTP 401)” means the client reached CLike without the header and tried OAuth: CLike has no OAuth (its /.well-known/oauth-* and /register answer 404) — add the Authorization header as above.

Extension operational MCP server

The VS Code extension can expose a second, operational MCP-compatible server that lets agents operate CLike through the same slash commands available in chat (see agent-operating-model.md, Model 2). Typical tools: clike_extension_status, harper_init, harper_next_action, harper_run_phase, harper_run_status, cancel_run, eval_run, gate_check, harper_kit_next, harper_continue_loop, harper_autopilot, rag_reindex, rag_docs_status, rag_docs_reindex_if_empty. It runs normal commands (/kit REQ-001, /eval REQ-001 --fix, /gate REQ-001, /finalize, …) through the chat’s governed handlers and does not duplicate Harper logic:

Because it can trigger phases that make local agents write files, it is locked down:

Current MCP usage model

The current MCP server is intended for:

It is not intended to replace the orchestrator HTTP APIs for:

harper_kit_prepare

One of the most important MCP tools is harper_kit_prepare(req_id).

It currently returns a read-only preparation bundle containing:

This makes MCP useful as an informational surface for external agents or tools without granting mutation capability.

Security posture

Using CLike from Claude Code and Codex (H2)

Setup commands: INSTALL §6.