MCP servers
Perch connects to outside apps and tools through the Model Context Protocol. Add connectors in Settings, choose whether each one runs on your computer or in the cloud, or write the config file yourself.
Perch can connect to external systems through the Model Context Protocol, or MCP. This lets Perch reach data and tools that are not files on your disk: issue trackers, databases, design tools, internal APIs, anything that speaks MCP. In the app these are called connectors. The tools from connected servers show up alongside Perch's built-in tools, and the model can call them directly.
The short version
Add a connector in Settings
In Perch Desktop, open Settings → Connections. The page lists your connectors with their status and how many tools each one offers, and under them a directory of connectors you can add: developer tools, data, design, productivity, payments, and search.
- Hosted apps sign in with your browser. Pick one, finish the sign-in, and its tools are available.
- Local tools run a program on this computer. Some need something installed first, such as Node.js or Docker, and the setup dialog says what. Some take an API key or an access token.
- Custom server adds any MCP server by hand: a local command with its arguments and environment, or a remote URL with its headers.
Connectors you add on the desktop are saved to ~/.perch/mcp.json. Reconnect all reconnects every server after a change.
In the CLI, /connectors shows the same list, and /connectors add <url> adds a remote server. /mcp is the same command.
Where a connector runs
Each connector has a Runs on setting with two places:
- Computer. It runs in the Perch desktop app and the CLI. A connector kept on your account runs wherever you are signed in. A connector set up in a config file runs on that computer only, with its own sign-in.
- Cloud. Cloud agents, routines, and cloud chats can use it, even with your computer off. Sign-ins for cloud connectors are stored encrypted on Perch's servers and are never shown back to you. Running a connector in the cloud is part of Pro and Ultra.
A connector that runs a program on your computer cannot run in the cloud. A remote server can run in either place, or both. On Perch AI Web, Settings → Connections manages the cloud side.
What ships by default
Perch Desktop creates ~/.perch/mcp.json on first launch with one server already configured:
- Playwright. Perch's built-in browser automation server, pinned to a tested version of
@playwright/mcp. It shows in the list with a Built-in tag.
You do not need to install or configure it.
How tools surface to the model
When an MCP server connects, Perch reads its tool list and converts each tool into a model-facing definition. The naming convention is mcp__<serverName>__<toolName>. For example, a tool called search on a server you named docs becomes mcp__docs__search, and it appears alongside built-in tools like readLocalFile or webSearch.
The model can call these tools in the same loop as any other tool. When your connectors offer so many tools that their definitions would take a large share of the context window, Perch holds the definitions back and loads the ones the model asks for.
Approvals
MCP tools follow the same permission modes as built-in tools. Perch uses the labels the server puts on each tool:
- A tool the server marks as read-only runs without asking, in every mode.
- Any other tool is treated as a change, including a tool with no label. In Default it asks for your approval. In Auto Review the reviewer decides. In Take the Wheel it runs.
- In Plan mode, a tool that would change something does not run.
When you approve a tool the server marks as non-destructive, you can allow it for the rest of the session.
Global and folder-scoped configs
MCP servers can be configured at two levels:
- Global. The file at
~/.perch/mcp.jsonapplies to every Perch session on your machine. This is where the default server and the connectors you add in Settings are saved. - Folder-scoped. A
.perch/mcp.jsonfile inside your workspace folder applies only when you are working in that folder. Folder configs override global configs by server name, so you can replace a global server with a different one for a specific project.
Environment variable expansion is supported. If a server needs an API key, you can reference it as ${YOUR_API_KEY} in the config and Perch will expand it from your environment.
Adding your own server in the file
To add an MCP server by hand, edit ~/.perch/mcp.json (for global) or .perch/mcp.json in your workspace folder (for a specific project). The structure is:
{
"servers": {
"my-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@some-org/some-mcp-server"],
"env": {
"API_KEY": "${MY_API_KEY}"
}
}
}
}Three transport types are supported:
- stdio. Runs a local process. Requires a
commandand optionalargsandenv. - http. Connects to a remote HTTP endpoint. Requires a
urland optionalheaders. - sse. Connects to a remote SSE endpoint. Requires a
urland optionalheaders.
After editing the file, use Reconnect all in Settings → Connections, or restart Perch.
Where MCP fits
MCP is for live systems that cannot be represented as files in a folder. If the data is already on your disk as a spreadsheet, a PDF, or a CSV, Perch reads it directly through the folder bridge. MCP is for everything else: external databases, APIs, and services that require a running process or authentication.
Where connectors work

