TokenFluid speaks MCP.

MCP — the Model Context Protocol — is an open standard for connecting AI agents to tools and data sources. It defines a common wire format so that an agent and a tool server can find each other, negotiate capabilities, and exchange structured calls and results. Without MCP, every agent-to-tool integration is a bespoke adapter. With MCP, one server works with every compatible agent.

MCP is transport-agnostic: it can run over stdio (for local tools like TokenFluid), over HTTP, or over a long-lived WebSocket. For TokenFluid, stdio is the right choice because the tool needs filesystem access to your repo. The agent spawns the MCP server as a child process and talks to it over its stdin and stdout.

If you have never worked with MCP, the mental model is JSON-RPC with a discovery handshake. The agent asks the server what tools it exposes, the server lists them with schemas, and the agent calls them as needed. Results come back as structured JSON. It is intentionally boring and easy to implement on both sides.

TokenFluid registers as an MCP server that exposes a small set of tools centered on the mounted working set. The agent calls mount_working_set with a task description, TokenFluid scores the local index, and a working set is mounted at a path the agent can navigate. The agent then uses its normal tools — rg, cat, sed, find — against that path.

This is the core design choice: TokenFluid does not replace your agent's tools. It changes what those tools operate on. Instead of grepping the whole repo, the agent greps a curated subset. The agent does not learn a new API; it just works in a smaller directory. Selection reasons are logged locally so you can audit why each file made the cut.

When the agent is ready to propose a change, it calls submit_patch with a unified diff. TokenFluid stages the patch for human approval and surfaces it in the dashboard. The patch never applies automatically — you approve every change explicitly. This is the patch approval flow described in the security docs.

The easiest path is tokenfluid mcp-install ., which writes the right config for the common agents. If your agent is not supported, or if you want to wire things up manually, the blocks below show the JSON for the three most common shapes.

Claude Code

1{
2  "mcpServers": {
3    "tokenfluid": {
4      "command": "tokenfluid",
5      "args": ["mcp-serve"]
6    }
7  }
8}

Cursor

1// cursor mcp_config.json
2{
3  "mcpServers": {
4    "tokenfluid": {
5      "command": "tokenfluid",
6      "args": ["mcp-serve"],
7      "env": {
8        "TOKENFLUID_REPO": "."
9      }
10    }
11  }
12}

Generic MCP client (YAML)

1# generic MCP client (stdio)
2command: tokenfluid
3args:
4  - mcp-serve
5env:
6  TOKENFLUID_REPO: "."

The TOKENFLUID_REPO environment variable tells the server which repo to operate on. If omitted, the server uses the current working directory at startup. For most setups you want to set it explicitly so the agent does not get confused if you launch it from a different directory.

TokenFluid exposes a deliberately small set of MCP tools. Fewer tools means the agent has less to learn and less to misuse. The table below is the full surface area — there is nothing hidden.

All tools return structured JSON. Errors are returned as MCP error responses with a message and a code — never as a successful response with an error field. This keeps the agent's error handling simple: if the call succeeded, the result is real.

Most MCP issues are wiring issues — the agent cannot find the server, the server cannot find the repo, or the versions do not match. The list below covers the four we see most often. If none of these match, run tokenfluid mcp-doctor for an automated diagnostic, or open a thread on the community Discord.

• Agent does not find TokenFluid tools

  The MCP server is not registered or your agent needs a restart. Run `tokenfluid mcp-install .` again and quit + reopen your agent. In Claude Code, also confirm `~/.config/claude-code/mcp.json` contains the tokenfluid entry.

• MCP version mismatch on startup

  Your TokenFluid CLI is older or newer than the MCP version your agent expects. Run `pip install --upgrade tokenfluid` and restart the agent. If the error mentions a specific protocol version, check the release notes — protocol bumps are flagged explicitly.

• Permission denied when mounting working set

  The .tokenfluid directory is not writable by the user running the agent. Check ownership of .tokenfluid at your repo root; if it is owned by root or another user, `sudo chown -R $USER .tokenfluid` and re-run. This usually happens after running the CLI under sudo once.

• Agent calls mount_working_set but gets an empty list

  The index is empty or stale. Run `tokenfluid status` — if file count is 0 or the index path does not exist, run `tokenfluid index .` to (re)build it. If file count is non-zero but selection is empty, the task description may not match any symbols; try a more specific task string.