# MCP

Enable this extension in the conversation's extension picker. Berry has a flat tool namespace, so
the three operations are exposed as `tools.mcp_list`, `tools.mcp_describe`, and `tools.mcp_call`.

## Configuration

By default, the extension reads `~/.config/berry/mcp.json` **on the conversation's machine**. Select
another path in the extension's configuration form; relative paths use the conversation's working
directory. A missing file means no configured servers.

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${WORKSPACE}"]
    },
    "docs": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
    }
  }
}
```

Stdio entries support `command`, `args`, `env`, and `cwd`. Commands use that machine's PATH, inherit
its environment, and run in the conversation's working directory unless `cwd` overrides it. HTTP
entries support `url` and `headers`; requests originate from that machine too, including DNS and
`localhost`. Only Streamable HTTP is supported, and redirects are refused.

Both transports support `enabled: false` and `timeout` in seconds (default 60). Initialization is
limited to at most 30 seconds. `${VARIABLE}` substitutions use the selected machine's environment;
missing variables fail explicitly. No shell or command substitution is performed.

Credentials stay in the configuration file or environment variables, not in configuration events.
Protect files containing credentials with appropriate permissions. The file is reread on each tool
operation; changed configurations get new connections. Connections are shared only within the same
machine, working directory, remote connection lifetime, and resolved server configuration, and close
after five idle minutes or when the extension reloads. Replacing an SSH connection opens fresh MCP
sessions on the next operation, without replaying calls.

Stdio shutdown force-stops owned process groups and bounds pipe draining, so escaped descendants
cannot keep an extension reload waiting indefinitely for inherited stdout or stderr. Startup
failures include a bounded stderr tail and the exit code when available.

## Tools

```javascript
text(await tools.mcp_list({}));
text(await tools.mcp_describe({ server: "docs", tool: "search" }));

const result = await tools.mcp_call({
  server: "docs",
  tool: "search",
  arguments: { query: "authentication" },
});
text(result);
for (const block of result.content) {
  if (block.type === "image") image(block);
}
```

Listing returns each server's status and short tool descriptions; one broken server does not hide
others. Pass `server` to restrict discovery. Describing a server without `tool` returns its complete
tool catalog and instructions.

Calls return the full MCP result, including `content`, `structuredContent`, and `isError`.
Tool-level errors remain results; transport and protocol failures reject. Cancellation and progress
are forwarded. A failed call is never automatically replayed; a disconnected or expired session
reconnects for the next operation.

OAuth sign-in, resources, prompts, sampling, and MCP Apps are not exposed in this initial version.
Servers needing authentication must accept credentials supplied in headers or environment variables.

The initial installation also adds streaming `Environment.fetch` and forceful process termination to
Berry's API. Use the header's restart button once to load those changes.