> ## Documentation Index > Fetch the complete documentation index at: https://docs.fermata.run/llms.txt > Use this file to discover all available pages before exploring further. # Connect Claude Code to Fermata's MCP server > Turn on Fermata's MCP server in Settings, register it with Claude Code or another MCP client, and check that it answers before you rely on it for work. > [!NOTE] > > The MCP server is off until you turn it on in Settings → MCP. The pane is there on every channel. Connecting takes two steps. You start the server in Fermata, then you tell your client where it is. For Claude Code, **Register** does the second step for you. ![The MCP pane in Settings showing the MCP server switch, a status row reading Running on 127.0.0.1 with a port, a health row reading Answering, the registration status, and the Unregister and Regenerate Token buttons](https://mintcdn.com/keliosllc/pg1SGBNjstRDbutF/images/screenshots/S29.png?fit=max\&auto=format\&n=pg1SGBNjstRDbutF\&q=85\&s=fb1b5d0af47e08e5133c034d651a8414) Settings → MCP: the server switch, its status and health, and the registration row ## Turn the server on Open Settings with **⌘,** and go to the **MCP** pane. The "Server" card leads with **MCP server**, captioned "Let an outside Claude Code drive pieces locally". Switch it on. The rows under it tell you where things stand: | Row | What it shows | | - | - | | "Status" | "Running on 127.0.0.1:8787" with the port it bound, or "Starting…", "Stopped", or "Failed" with the reason and a **Retry** button. | | "Health" | A live round trip to the server: "Answering, 14 tools" when it works, "Not answering" with the reason when it does not. **Check** runs it again. | | "Claude Code" | "Registered" ("Every claude session sees this server") or "Not registered" ("Sessions connect per command below"). | "Answering" is the quickest way to tell a broken connection from a quiet one. The number is how many tools the server serves. Fermata remembers the switch. The next time it launches with the switch on, the server starts on its own. ## The port The "Port" card holds **Preferred port**, 8787 unless you change it. Type a number between 1024 and 49151 and press **Apply**; anything else is refused inline with the reason, and nothing is saved. The new port applies at the next start or **Retry**, so a call already in flight is never cut off. Fermata tries the preferred port first, then the next nine, then any port the system offers. When it lands somewhere else, a "Bound port" row says so: "Not the preferred port 8787. Retry in about 30 seconds." Either another app holds the port, or connections Fermata just closed there are still winding down. A client registered on the preferred port cannot reach the moved server, so press **Retry** once it clears. ## Register with Claude Code Once the server is running, an "Endpoint" card appears. Its "Claude Code registration" row carries **Register**. **Register** writes one entry, named `fermata`, into `~/.claude.json`, the user-scope config file the Claude Code CLI reads. From then on every `claude` session that reads that file sees Fermata, in any directory, with no extra flag. Nothing else in the file changes. If the file already has a `fermata` entry pointing somewhere else, Fermata asks first with "Replace the Fermata entry in Claude Code?" and shows where the old one points; **Cancel** leaves the file exactly as it was. Registration writes that one file only, so a project whose sessions use their own Claude config directory (Settings → Claude Code → **Claude config directory**) does not see the entry; connect a terminal session for that account with the **One-off** command below. **Unregister** takes the entry back out and leaves every other server in the file alone. The token is stored in your Keychain and the port is pinned, so the registered URL keeps working across a Fermata relaunch. Two things change it: a port move, and regenerating the token. ## Other clients and one-off sessions The "Connect a client" card has three methods under "Method", each with text you can copy straight into a terminal: * **One-off** starts a single connected session from any directory: `claude --mcp-config` pointed at a connection file Fermata keeps up to date. The file is re-read on every run, so this command survives relaunches, port moves, and token changes. * **Shell alias** is the same command as a `claude-fermata` alias for your `~/.zshrc`. * **Register** is the `claude mcp add-json fermata … -s user` command that does what the **Register** button does, and the matching `claude mcp remove fermata`. The "Copy" row has two buttons. **Instructions** copies the method's text. **Inline Config** copies the raw connection as JSON, an `mcpServers` object with one `fermata` entry of type `http`, for any MCP client that takes a static config. The URL inside carries the token: `http://127.0.0.1:/mcp/`. Treat it like a password. Anyone on your Mac who has it can drive your pieces. ## Retire the token **Regenerate Token**, in the "Endpoint" card, mints a new token after you confirm "Regenerate the MCP token?". Every client holding the old URL stops working, and a `claude` session connected right now is cut off and has to be started again. Fermata rewrites its own registration in `~/.claude.json` for you, so registered sessions keep working once restarted. The server does not rebind and the port does not change. If the Keychain refuses the token, an "Auth token" row reads "This launch only": the URL changes at the next relaunch, and anything you register has to be registered again. ## After Fermata restarts A Claude Code session that was connected when Fermata quit loses the server; the tools stop resolving. Once Fermata is running again, run `/mcp` in that session to reconnect. The URL is the same, so nothing needs re-registering. If the tools still do not resolve, check Settings → MCP. "Health" should read "Answering", and "Claude Code" should read "Registered". A "Bound port" row means the server moved; press **Retry** once the port clears. ## Turning it off Switching **MCP server** off stops the server and removes the registration Fermata wrote. Switching it back on starts the server and registers it again. Fermata can also pause the server remotely if it turns out to be causing trouble. The pane then reads "Paused remotely", the server stays stopped, and your switch keeps its setting, so the server comes back on its own when the pause lifts. Either way, a call waiting on a [confirmation card](https://docs.fermata.run/mcp/consent-and-safety.md#the-cards) is denied. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.