MCP servers

MCP lets a model use tools somebody else wrote: a database, an issue tracker, your design system, a search index. OptiQ Code and the Lab both speak it over stdio, which is the transport nearly every MCP server ships with, and it reads the configuration you already have rather than asking you to write a new one.

Bring the servers you already have

If you use Claude Code, Claude Desktop, Codex, opencode, OpenClaw, Hermes Agent, Mistral Vibe or Cursor, your servers are already described on disk. Import them:

# see what would be imported, from every client it knows
$ optiq code mcp import

# write them
$ optiq code mcp import --yes

# or just one client
$ optiq code mcp import claude-desktop --yes

Nothing is written without --yes. Servers you already have keep their existing definition, so re-running it is safe.

Adding one by hand

$ optiq code mcp add filesystem npx -y @modelcontextprotocol/server-filesystem ~/code
$ optiq code mcp add gh docker run -i --rm ghcr.io/github/github-mcp-server --env GITHUB_TOKEN="$TOKEN"

$ optiq code mcp list        # what is configured
$ optiq code mcp test        # start them and show the tools
$ optiq code mcp remove gh

optiq code mcp test is the one worth running after any change. It actually spawns each server and lists what it exposes, so a typo in a path or a missing token shows up there rather than halfway through a task.

The config file

Servers live in ~/.optiq/code/mcp.json, or <repo>/.optiq/mcp.json for one project, where the repo wins on a name clash. The format is the mcpServers object every other client uses, so you can paste one in directly:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/code"],
      "env": {"API_KEY": "..."},
      "enabled": true
    }
  }
}

enabled is the one field that is ours. Leave it out and the server is on; set it to false to park a server without deleting a definition that may have a token in it.

Using them

Connected tools appear to the model as mcp__<server>__<tool>, and the status bar shows how many are live. In the TUI, /mcp lists every server, its tools, and which of them are read-only.

The prefix is not decoration. The reference filesystem server publishes tools called read_file, write_file and edit_file, which are the names of three of OptiQ Code's own. Without the prefix, connecting it would quietly replace the editor the agent depends on.

Approval and modes

An MCP tool is someone else's code, reached over a pipe, and its description is text that arrives in your model's context. So OptiQ Code treats it the way it treats an edit:

Read-only comes from the server's own readOnlyHint. A tool that says nothing is treated as not read-only: the failure worth avoiding is a plan-mode agent posting to a channel because a server forgot to annotate itself.

In the Lab

The same servers back the Lab's chat. Configure them once and both OptiQ Code and the Lab can use them, which is why the config lives at ~/.optiq/mcp.json rather than under either one.

Open Model & params on the Chat page and the MCP row lists each connected server with its tool count. Nothing else to switch on: if servers are configured, the model can use them.

The servers start once for the Lab process, not once per conversation, so the cost of launching them is paid at first use and calls after that are immediate. Nothing is spawned at all if you have no servers configured.

What a server can and cannot reach

An MCP server is somebody else's program. A line like npx -y @someone/server fetches a package and runs it on your machine, and the tool descriptions it publishes are text that goes into your model's context. Connect servers you would be willing to run any other way.

OptiQ narrows what one can reach:

• Not your credentials. A server gets a short list of variables it needs to run (PATH, HOME, locale, temp dir) and nothing else. Before this was fixed, a server could read every token in the environment. Anything a server genuinely needs goes in its own env block, where it is scoped to that server and visible in the config.
• Not your whole context. At most 64 tools per server, descriptions capped, and a single result capped at 100,000 characters. Anything dropped is reported rather than quietly cut.
• Not without you. Anything not marked read-only needs approval before it runs, and the prompt names the server.

What OptiQ cannot do is make a description honest. A server can put anything in one, including text aimed at your model, and no amount of filtering fixes that. The defence is that the text is data rather than instruction, it is attributed to its server, it is bounded, and acting on it still needs your approval.

What it costs

Every connected tool is described to the model on every turn. One 14-tool server is about 2,300 tokens per request before you have typed anything, and a few servers is a real bite out of a local model's window. OptiQ warns past roughly 4,000 tokens.

So connect what you use. optiq code mcp list shows what is on, and setting "enabled": false parks a server without deleting a definition that may have a token in it.

What is not supported yet

stdio only. Remote HTTP and SSE servers are recognised and reported as skipped rather than silently ignored, but OptiQ Code cannot connect to them yet. Tools are supported; MCP resources and prompts are not.

A server that fails to start costs you its tools and nothing else. The error is shown, the other servers carry on, and the agent keeps working.