MCP servers

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: legal databases, browser automation, internal APIs, anything that speaks MCP. The tools from connected servers show up alongside Perch's built-in tools, and the model can call them directly.

What ships by default

When you first launch Perch Terminal Desktop, it creates a config file at ~/.perch/mcp.json with two servers already configured:

• CourtListener. A legal research server that can search case law, look up citations, retrieve opinion text, find related cases, and pull docket entries. It connects to the CourtListener database, which covers federal and state courts. A bundled API token is included, so it works on first launch without configuration.
• Playwright. A browser automation server pinned to a tested version of @playwright/mcp. This is what powers Perch's browser delivery: navigating pages, clicking elements, typing into fields, and reading what is on screen.

You do not need to install or configure either one. They connect automatically when Perch starts.

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, CourtListener's case search becomes mcp__courtlistener__search_cases, and it appears alongside built-in tools like readLocalFile or webSearch.

The model sees these tools as first-class. It can call them in the same loop as any other tool, and the results come back as structured content that Perch can cite and act on.

Global and folder-scoped configs

MCP servers can be configured at two levels:

• Global. The file at ~/.perch/mcp.json applies to every Perch session on your machine. This is where the default servers are configured.
• Folder-scoped. A .perch/mcp.json file 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

To add an MCP server, 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 command and optional args and env.
• http. Connects to a remote HTTP endpoint. Requires a url and optional headers.
• sse. Connects to a remote SSE endpoint. Requires a url and optional headers.

After editing the config, restart Perch or run the reconnect command. The new server connects on the next launch.

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.

The operator and agents→

How Perch goes beyond chat to read files, run analysis, and coordinate workers.

Security and data→

How Perch handles your files, your data, and what is processed off your device.