# Connect an AI agent with MCP

Thymer speaks MCP, the protocol AI clients use to work with tools. The server runs on your computer, and an agent connected to it reads and edits your workspace as you, within the access you give it.

## In the desktop app

1. Open **Settings → MCP (AI Agents)**.
2. Under **Workspace Access**, set the workspace you want to make accessible. Everything else stays **Off**.
3. Click **Connect**. The dialog shows **MCP server active** and the port.

The server listens on `http://127.0.0.1:13100/mcp`.

## In the browser

The browser can't open a port, so a small companion does it. Download `thymercli` from [thymer.com/mcp](https://thymer.com/mcp) and run it:

```bash
thymercli
```

Then open **Settings → MCP (AI Agents)** in Thymer, set the workspace access, and click **Connect**. The CLI bridges requests to your signed-in browser tab, so keep both running. `thymercli mcp --no-repl` starts the server without the interactive prompt.

Run one server at a time: the desktop app and `thymercli` both default to port 13100.

## Add it to your client

Clients that speak HTTP take the address directly. Choose Streamable HTTP if asked:

```text
http://127.0.0.1:13100/mcp
```

Clients that launch a process use the CLI as a proxy. Configure them to run the installed executable with `stdio` as the argument; use the full path if the client doesn't see your shell's PATH.

```bash
thymercli stdio
```

Then ask the agent to list the workspaces and read a page you know. If it sees the right workspace and the right text, you are connected.

## Tool Mode and Script Mode

In **Tool Mode** the agent gets one tool per operation: list, read, search, write. In **Script Mode** it gets a bash-style shell over a virtual filesystem of your workspace, which is usually more efficient for agents that are good with the command line. Switch in the MCP settings and refresh the client's tool list afterwards. The paths in Script Mode exist only inside that shell. To give an agent real files on your disk, use [Markdown Mirror](../markdown-mirror.md).

## Access

Access is per workspace and per connection: **Off**, **Read Only** or **Read & Write**. Start with Read Only for anything that only needs to read or summarize. Writes land in the shared workspace like your own edits do, with your name on them.

The agent runs on your machine, but most AI clients send what they read to their model provider. Choose the client and the workspace accordingly.

## When it doesn't connect

- No server: check for **MCP server active** in the desktop app, or that `thymercli` is still running, and that the client uses the same port.
- Port in use: stop the other server, or start one of them on another port with `-p`.
- Reads work but writes fail: the workspace is on **Read Only**.
- The agent sees no workspaces: the workspace is **Off**, or in the browser you haven't clicked **Connect** since starting the CLI. `thymercli status` and `thymercli workspace list` show what the server sees.
- A remote agent can't reach it: inside a container or on a remote host, `127.0.0.1` points at that machine itself.