Tidebreak documentation
MCP servers
Connect external Model Context Protocol tool servers over stdio or HTTP.
Tidebreak is an MCP client. Tools from a connected server are advertised to the
agent alongside its own, namespaced as mcp__<server>__<tool>.
Adding a server
Settings → Connected apps, in the MCP servers section. Servers are added and reconnected in place — no shell, no config file, no restart.
Two transports:
Local process (stdio) — Tidebreak launches the server as a child process.
| Field | |
|---|---|
| Executable | The program to run: a bare name such as npx, or an absolute path. A bare name is found on your login-shell PATH, and Settings shows the path it resolved to. |
| Arguments | One per row. |
| Working directory | Where to run it. |
| Environment | Name/value pairs passed to the process. The values are kept in the OS credential store. |
| Forward environment names | Variables to pass through from your own environment by name, without copying their values into the config. HOME and PATH are forwarded by default, so a script such as npx finds node. The forwarded PATH keeps only absolute directories. A name you list here or under Environment replaces the default, and gets no default while its value is missing. |
In the desktop app, saving a local server asks first in an OS dialog, which
names the absolute path of the program that will run. For a bare name such as
npx, Tidebreak records that path. Each time the server starts, Tidebreak
looks the name up again and starts it only if it finds the same program. If
it finds another one, for example an npx that appeared in a directory
earlier on your PATH, the server does not start, and its row names both
paths. To run the new program, save the server again and allow it in the
dialog.
The Tidebreak CLI, a self-hosted server, and a desktop window attached to a remote machine show no such dialog. There, a bare name runs whatever it resolves to each time the server starts.
Remote endpoint (HTTP) — Tidebreak connects to a URL.
| Field | |
|---|---|
| Server URL | The endpoint. |
| Authentication | None, Bearer token, stored (kept in the OS credential store and sent only to this server), Bearer token from a variable (the name of an environment variable holding the token), or OAuth (sign in with your browser). |
| Headers | Up to eight custom headers, such as X-Api-Key. The values are kept in the OS credential store. |
| Request timeout (ms) |
A stored bearer token or header value is shown as set, never shown again, and goes only to the URL you entered it for. Changing the URL's scheme, host, port, path, or query drops the stored values, and the editor says so before you save. Enter them again for the new URL.
A server that refuses its bearer token and offers an OAuth sign-in instead is saved with Sign-in available, and Use OAuth switches it and opens the sign-in page.
Every server has a Namespace, which is the <server> part of the tool
names, and an Enabled switch.
Save and verify connects and lists the server's tools, so a bad command or URL fails at configuration time rather than mid-turn. Reconnect and refresh tools picks up changes to a server you are developing.
A health chip shows Healthy, Connecting…, Reconnecting, Needs attention, Disabled, or Not verified.
The approval boundary
Every MCP tool is sensitive. There is no way to mark one safe, and no inspection of what a server's tool claims to do. In Ask and Auto, each call asks.
That is deliberate. Tidebreak classifies its own tools because it knows what they do. It knows nothing about a third-party server's tools beyond the names and descriptions the server supplies — and the server wrote those.
Descriptions and results from an MCP server are untrusted input. A server can put instructions in a tool description or a tool result, and those instructions reach the model. Connect servers you trust, and read approval cards for MCP calls rather than clicking through them.
Running Tidebreak as an MCP server
The reverse direction also exists: tidebreak mcp <workspace> serves
Tidebreak's read-only file tools to another MCP client over stdio. See
Running headless.