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

From a local checkout:

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.

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 Desktop¶

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

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

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¶

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¶