How the MCP Server Works

Kangentic ships a Model Context Protocol server inside the app. Most agents it spawns get tools for working with the board, backlog, sessions, and the embedded browser while they run, so an agent that discovers follow-up work can file it directly instead of asking you to type it in.

This page covers how that connection is made. For the tools themselves, see the Tool Reference; for the trust boundary, see Security & Network Access.

The request path

The server runs in-process inside Kangentic’s main process. There is no separate server binary and no child process spawned for Kangentic itself.

Agent calls an MCP tool (e.g. kangentic_create_task)
  HTTP POST http://127.0.0.1:<port>/mcp/<projectId>
  (X-Kangentic-Token header, JSON-RPC body)
  In-process MCP HTTP server, Streamable HTTP transport
  Tool handler runs against that project's database
  Response returns in the same HTTP request (no SSE, no file polling)
  Board refreshes over IPC

Two things are worth noticing in that URL. The port is chosen at random on each launch, and the project ID is part of the path, so a config file left over from another project cannot be pointed at the current one.

How a session gets connected

Kangentic delivers its MCP config per session rather than editing anything you own. What that looks like differs per CLI, because no two of these accept MCP config the same way:

Agent	How the config arrives	Where the token ends up
Claude Code	--mcp-config pointing at .kangentic/sessions/<sessionId>/mcp.json	Session file, inside .kangentic/
Codex CLI	-c mcp_servers.kangentic.* overrides that apply to that invocation only	Environment variable
Gemini CLI	An mcpServers entry in <cwd>/.gemini/settings.json	Project file, removed on exit
Cursor CLI	Not wired	-
GitHub Copilot CLI	--additional-mcp-config, which augments rather than replaces your own config	Session-adjacent file
Grok Build	An [mcp_servers.kangentic] block in <cwd>/.grok/config.toml that references the URL and token by variable name, plus an --allow pre-approval for Kangentic’s tools	Environment variable (the file holds only the variable names)
Antigravity CLI	A workspace plugin under <cwd>/.agents/plugins/kangentic/, which connects at the first agent turn	Project file, removed on exit
OpenCode	The OPENCODE_CONFIG_CONTENT environment variable, so your opencode.json is never modified	Environment variable (local spawns only)
Aider	Not possible: Aider is not an MCP client	-
Qwen Code	An mcpServers entry in <cwd>/.qwen/settings.json	Project file, removed on exit
Kimi Code	--mcp-config-file pointing at the session’s mcp.json	Session file
Factory Droid	<cwd>/.factory/mcp.json referencing ${KANGENTIC_MCP_TOKEN}	Environment variable (the file holds only the variable name)
Warp (Oz CLI)	Not wired	-
Ollama	Not possible: Ollama is not an MCP client	-

Three properties hold across every one of those paths. The URL and token are per launch. No MCP server entry is ever written into the CLI’s global config, so nothing Kangentic delivers outlives the project or the session it belongs to. And the entry is additive, so MCP servers you configure yourself keep working alongside Kangentic’s.

The rows that write into your project directory (Gemini, Grok, Antigravity, Qwen, Droid) also stay out of git: when Kangentic is the one creating the file, it seeds the path into the repository’s local .git/info/exclude, so the file never shows up in git status and cannot ride along in a git add -A. A file you already had keeps its normal git visibility. Your repository’s .mcp.json and .gitignore are never touched either way.

For Claude specifically, the spawn also adds kangentic to enabledMcpjsonServers in ~/.claude.json so the server is pre-trusted, and the agent reads both your own .mcp.json and the Kangentic config on startup. Codex, Gemini, Grok Build, Antigravity, and Qwen Code each keep their own folder-trust store, and Kangentic pre-approves the spawn directory in every one of them. Without that an untrusted folder would either disable every configured MCP server outright or prompt on every single task, since Kangentic gives each task its own worktree and neither store inherits an answer from the parent folder. An explicit trust decision you have already made, at the path or above it, is never overruled.

Note

The token is regenerated on every Kangentic launch. A session spawned before a restart is holding a stale token, which is why a tool call can start returning 401 after you restart the app. Respawn the session and its config is rewritten.

Why agents never get a permission prompt

Agents Kangentic spawns do not stop to ask about Kangentic’s own tools. In Claude Code, three layers cover that, because a single allow rule does not hold across every permission mode:

Layer	Covers	How
Auto-allow injection	default and acceptEdits modes	mcp__kangentic is appended to permissions.allow in the per-session merged settings, append-if-absent
Read-only annotations	plan mode	Allow rules do not punch through plan mode, so auto-approval there comes from each tool’s readOnlyHint
Auto-mode allow rule	auto mode	Auto mode runs its own natural-language classifier that ignores permissions.allow, so a plain-language rule is appended to autoMode.allow

All three are written only into the regenerated per-session settings, never back into your own settings files. An explicit deny of mcp__kangentic still wins, because deny outranks allow.

The plan-mode row is a deliberate asymmetry rather than a gap. Read-only tools run unprompted while planning; mutating tools still prompt, so the plan-mode auto-approval surface is exactly the read-only set. See Tool annotations.

Other CLIs use their own mechanism where they have one. Grok Build takes an --allow "MCPTool(kangentic__*)" on the spawn command, which is the same idea in grok’s own vocabulary. Elsewhere the column’s permission mode is what decides, the same as for any other tool the agent reaches for.

Turning it off

The server is enabled by default. Toggle MCP Server off in Settings, or set mcpServer.enabled to false, and a spawned session gets none of the wiring in the table above: no flag, no config file, no environment variable. See the Configuration Reference.

When tools do not show up

1. Ask the agent to list its MCP servers (/mcp in Claude and Codex, gemini mcp list, droid mcp list). If kangentic is absent, the wiring did not arrive.
2. Check the config your agent’s row in the table above names. For Claude and Kimi that is .kangentic/sessions/<sessionId>/mcp.json, which should carry a kangentic entry with a url on 127.0.0.1 and an X-Kangentic-Token header.
3. Check the agent’s command line includes the flag from that row. The spawn command is echoed into the terminal scrollback, so you can read it back.
4. For Claude, check ~/.claude.json lists kangentic under enabledMcpjsonServers for that project path.
5. For Codex, Gemini, Grok Build, Antigravity, and Qwen Code, an untrusted folder disables MCP entirely. Confirm the spawn directory is trusted.
6. If calls return 401, the session is holding a token from a previous launch. Respawn it.
7. If calls return 404, the URL path does not match a registered project. Confirm with kangentic_list_projects.

An agent can also simply not reach for the tools, defaulting to its own built-in task list instead. Naming the tool in your prompt (“use kangentic_create_task to file that”) is usually enough.

Next steps

See also:

• Tool Reference - all 63 tools, grouped as the settings panel groups them
• Security & Network Access - the token, the bind address, and what an agent can reach
• Agent Orchestration - the board behavior these tools drive
• Custom Workflows - auto-commands, the other half of hands-free transitions