MCP and Agent Workflows¶

solumbe can run as a stdio MCP server so agent hosts can ask for repository context without scraping terminal output.

Start The Server¶

Install the published package when you want Solumbe available as a local command:

npm install -g @bashbop/solumbe
solumbe doctor

Or start from a local checkout:

git clone https://github.com/BASHBOP/solumbe.git
cd solumbe && npm ci
node src/cli.js doctor

node src/cli.js mcp

The MCP server uses stdio. The agent host starts solumbe mcp as a child process and speaks JSON-RPC over standard input and output.

Connect Your Agents¶

One command adds Solumbe to every agent host it finds on the machine:

solumbe install --host all

• --host claude-code,cursor configures only the hosts you name, and fails if one of them is missing.
• --dry-run prints what would change and touches nothing.
• --canvas http://127.0.0.1:7801 adds the Realtime Canvas variables to each host.
• --json returns the result for scripts.

Before it writes anything, the installer starts the server once and checks that it answers an MCP initialize request. Each host gets the absolute path of node and of Solumbe's CLI, not a bare solumbe command, because Claude Desktop, Cursor and VS Code start servers without your shell PATH, so under nvm, Volta or Homebrew they cannot find solumbe or node on their own. JSON configs are merged in place, and the original is kept as <file>.solumbe.bak. A config it cannot parse, such as a mcp.json with comments, is left untouched and reported. An existing solumbe entry is replaced, and the env it carried is kept on the new one; the summary names those variables and never prints their values. Other entries that still launch Solumbe, such as one left from before the 4.0.0 rename, are listed so you can remove them.

Restart each host after running it. Run it again after you upgrade Node or move a checkout, so the pinned paths stay current.

The sections below show what the installer writes, for setting up a host by hand.

MCP Client Examples¶

Use the installed solumbe binary where available. A local checkout is equally valid when you are developing Solumbe itself.

Generic stdio client¶

Many MCP clients use this shape:

{
  "mcpServers": {
    "solumbe": {
      "command": "node",
      "args": ["/absolute/path/to/solumbe/src/cli.js", "mcp"],
      "env": {}
    }
  }
}

Some hosts also require an explicit "type": "stdio" field. Check the host's current MCP schema before copying a config into a shared repository.

For a local checkout instead of a global install:

{
  "mcpServers": {
    "solumbe": {
      "command": "node",
      "args": ["/path/to/solumbe/src/cli.js", "mcp"],
      "env": {}
    }
  }
}

Keep /path/to/solumbe as a private local path. Do not commit machine-specific absolute paths to public documentation or shared repositories.

Claude Code¶

Add the server at user scope so every project sees it:

claude mcp add-json solumbe '{"type":"stdio","command":"solumbe","args":["mcp"]}' --scope user

Use --scope project to write a shared .mcp.json into one repository instead. Run claude mcp list to confirm it shows solumbe ... Connected, then start a new session; the tools appear as mcp__solumbe__*.

Project settings¶

This repository commits .claude/settings.json with what a session working in it needs and nothing personal. MCP servers, personal hooks, absolute paths and anything else that belongs to one machine stay in ~/.claude/settings.json or the ignored .claude/settings.local.json.

Deny wins over allow and ask in every scope, and a rule in ~/.claude/settings.json or .claude/settings.local.json adds to these rather than replacing them.

Headless gate summary in CI¶

.github/workflows/claude-gate.yml runs Claude Code headless on every pull request:

1. The workflow runs solumbe gate . --base origin/<base> --head HEAD --json itself and keeps the result.
2. claude -p runs the same gate and answers with a JSON summary (verdict, headline, checks, risks, nextSteps), using --output-format json and the --json-schema that node scripts/claude-gate-summary.mjs --schema prints.
3. scripts/claude-gate-summary.mjs refuses a run that did not succeed, a summary off the schema, a verdict that differs from the workflow's gate, a check the gate never ran or reported with another status, and a WARN or FAIL check left out. A refused summary turns the job red and is never posted.
4. A valid summary is posted as one PR comment, edited in place on later pushes, and added to the job summary. The gate output, Claude's envelope and the comment are uploaded as the claude-gate-summary artifact.

The run is held to the gate: --permission-mode dontAsk with --allowedTools "Bash(node src/cli.js gate *)" denies every other tool, and --bare --setting-sources user keeps this repository's hooks and wider allow rules out of CI. --max-budget-usd 1 caps one run, and the CLI version is pinned in CLAUDE_CODE_VERSION.

It reads the ANTHROPIC_API_KEY repository secret. When the secret is unset, or the PR comes from a fork (which GitHub never hands a secret on pull_request), every step after the key check is skipped and the job passes with a notice. It is advisory: it is not a required check, and Solumbe readiness in solumbe CI stays the blocking gate. Making it required is a branch-protection change for the maintainer.

Claude Desktop¶

Claude Desktop uses claude_desktop_config.json with a top-level mcpServers object.

{
  "mcpServers": {
    "solumbe": {
      "type": "stdio",
      "command": "solumbe",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Claude Desktop starts servers without your shell PATH, so under nvm, Volta or Homebrew a bare solumbe may not be found. Use the absolute paths from which node and npm root -g ("command": "/path/to/node", "args": ["/path/to/node_modules/@bashbop/solumbe/src/cli.js", "mcp"]), or let solumbe install --host claude-desktop write them. The same applies to Cursor and VS Code.

After editing the config, fully restart Claude Desktop. If the server does not appear, run solumbe doctor and solumbe mcp manually in a terminal first, then check the MCP logs for the host.

Reference: Model Context Protocol local server guide.

VS Code¶

VS Code stores MCP server configuration in mcp.json. Workspace-level configuration lives at .vscode/mcp.json; user-level configuration is also supported by VS Code.

VS Code uses a top-level servers object:

{
  "servers": {
    "solumbe": {
      "type": "stdio",
      "command": "solumbe",
      "args": ["mcp"]
    }
  }
}

Useful commands from the Command Palette:

• MCP: Add Server
• MCP: List Servers
• MCP: Reset Cached Tools
• MCP: Open Workspace Folder MCP Configuration
• MCP: Open User Configuration

Reference: VS Code MCP configuration reference.

Cursor¶

Cursor uses mcp.json with a top-level mcpServers object.

{
  "mcpServers": {
    "solumbe": {
      "command": "solumbe",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Use a project config when solumbe should only be available for one workspace. Use a global config only when you want the server available across projects. Project .cursor/mcp.json is local editor config and is not committed in this repository.

Reference: Cursor MCP docs.

Gemini CLI¶

Gemini CLI supports stdio MCP servers. Add Solumbe to user-level ~/.gemini/settings.json or project-level .gemini/settings.json:

{
  "mcpServers": {
    "solumbe": {
      "command": "solumbe",
      "args": ["mcp"]
    }
  }
}

Restart Gemini CLI and run gemini mcp list (or /mcp list) to confirm the server is connected. Gemini CLI also supports Skills, so use the Solumbe trusted agent workflow before asking it to edit code.

Reference: Gemini CLI MCP servers.

Kimi Code CLI¶

Kimi Code CLI supports stdio MCP servers. Add Solumbe to the user-level ~/.kimi-code/mcp.json or project-level .kimi-code/mcp.json file:

{
  "mcpServers": {
    "solumbe": {
      "command": "solumbe",
      "args": ["mcp"]
    }
  }
}

Verify the server with kimi mcp list. Kimi Code also recognises local skills; keep the agent workflow in the repository so it remains portable across tools.

Reference: Kimi Code CLI MCP support.

Grok¶

Grok custom MCP connectors use a publicly reachable MCP endpoint. Solumbe's local solumbe mcp command is stdio-only, so it must not be exposed through a local tunnel by default. Until Solumbe offers a reviewed remote MCP deployment, use the structured-handoff path instead:

solumbe context "<task>" --path . --out .solumbe/context-pack.md
solumbe pr . --base origin/main --out .solumbe/pr-review.md

Share only a sanitised summary or approved artifact with Grok. A future remote connector must receive a separate security, access-control, and data-boundary review before it can be presented as direct support.

Reference: Grok custom MCP connectors.

Codex CLI¶

Codex CLI starts stdio MCP servers from ~/.codex/config.toml:

[mcp_servers.solumbe]
command = "solumbe"
args = ["mcp"]

ChatGPT¶

ChatGPT reaches MCP servers through connectors that call a remote endpoint; it does not start a local stdio process. The Grok guidance above applies unchanged: do not tunnel solumbe mcp to the internet. Use Codex CLI for direct tool access, or hand ChatGPT a reviewed artifact from the structured-handoff commands.

Realtime Canvas and model routing (opt-in)¶

Two environment variables in a host's MCP config let that host appear on a local Solumbe Realtime Canvas, an observer that listens on 127.0.0.1 and shows each request becoming an intent, a context, a tier and a result. A third lets model_route ask a calibrated model. All three are off unless set.

The tap sends the request text, the tool name and the host label. It never sends a tool result, a path argument or file contents, and it never waits for the canvas, so a canvas that is down or slow cannot delay an answer.

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "solumbe": {
      "command": "solumbe",
      "args": ["mcp"],
      "env": { "SOLUMBE_CANVAS_URL": "http://127.0.0.1:7801", "SOLUMBE_HOST": "cursor" }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "solumbe": {
      "type": "stdio",
      "command": "solumbe",
      "args": ["mcp"],
      "env": { "SOLUMBE_CANVAS_URL": "http://127.0.0.1:7801", "SOLUMBE_HOST": "vscode" }
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.solumbe]
command = "solumbe"
args = ["mcp"]
env = { SOLUMBE_CANVAS_URL = "http://127.0.0.1:7801", SOLUMBE_HOST = "codex" }

Claude Desktop takes the same env object as Cursor. Claude Code already reaches the canvas through its UserPromptSubmit hook, so leave the tap off there, or each prompt is shown twice. Keep TYPESAFE_API_KEY in your shell environment or the host's secret store rather than in a config file you might commit.

MCP Tool Surface¶

Solumbe exposes 14 MCP tools for deterministic repository context and merge evidence.

Legacy tool names¶

The older names below still work through tools/call, although tools/list does not advertise them. They date from solumbe 2.0, which folded 18 tools into 11. Each call is forwarded to its canonical tool with the arguments translated, so a host configured with the old names keeps working. They still work in 3.x, and no release has been named to remove them; use the canonical names in new configs.

The four find_* tools pass limit through, use the first of paths when path is absent, and drop any other argument.

Agent Loop¶

Trusted Agent Workflow¶

The server sends its workflow (which tool to call at each stage of a task) in the MCP initialize result as instructions. A host that surfaces server instructions, as Claude Code does, therefore follows the same workflow without a CLAUDE.md, AGENTS.md or .cursor/rules entry. The text lives in src/lib/agent-workflow.js, and a test fails if it names a tool the server does not list.

This workflow works across Codex, Claude, Cursor, Gemini, Kimi, and any agent that can use local MCP or a structured handoff:

Request -> context -> scoped change -> validation -> review context -> gate -> human decision

The host does not determine whether a change is trustworthy. Solumbe provides local, deterministic evidence; tests, protected branches, and a human reviewer provide accountability. Do not represent a passing gate as an automatic merge approval. A workspace-level gate binds local staged evidence across repositories; it does not establish hosted CI state, GitHub approval, or mergeability.

Host Guidance¶