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 MCP tool reference; for the trust boundary, see MCP security and 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 when the folder’s last session exits
Cursor CLI	A `kangentic` entry in `<cwd>/.cursor/mcp.json` whose URL and token are `${env:...}` references, plus `--approve-mcps`	Environment variable (the file holds only the variable names)
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 when the folder’s last session exits
Goose CLI	Not wired	-
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 when the folder’s last session exits
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, Cursor, 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.

Several sessions can share one folder, so Kangentic holds a project-file entry per session and removes it only when the last session using that folder ends. Gemini, Qwen, Droid, and Antigravity write the session’s URL itself into the shared file, so the last session to start decides the URL the others read. That is why none of the four can be a workflow’s agent, whose server is scoped by its own URL. Grok’s and Cursor’s files hold only variable names, and each session’s own URL and token ride its environment.

Cursor’s --approve-mcps loads the project’s MCP servers without a per-server approval prompt that no Kangentic session could answer. It approves every server in that .cursor/mcp.json, yours included, as running Cursor there with the flag yourself would. A .cursor/mcp.json Kangentic cannot parse, such as one with comments, is left as it is, and the session starts without Kangentic’s tools.

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. Claude’s per-directory “Is this a project you trust?” prompt is pre-accepted in the same file (projects[<path>].hasTrustDialogAccepted), so a fresh worktree never stops on it. 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. Grok Build’s trust covers every folder below a trusted one, so for Grok Kangentic trusts only the worktrees it creates and never the project folder itself: a Grok session that runs in a project folder you have not trusted in grok starts without Kangentic’s tools.

When agents skip the permission prompt

Claude Code and Grok Build sessions Kangentic spawns do not stop to ask about Kangentic’s own tools. Every other agent applies its own approval rules to them, as it would to any MCP server, so depending on the column’s permission mode it may ask in its terminal before a call. 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. Switch MCP server off in Settings > MCP Server, 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

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.
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.
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.
For Claude, check ~/.claude.json lists kangentic under enabledMcpjsonServers for that project path.
For Codex, Gemini, Grok Build, Antigravity, and Qwen Code, an untrusted folder disables MCP entirely. Confirm the spawn directory is trusted.
If calls return 401, the session is holding a token from a previous launch. Respawn it.
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.