# pi-codemode-mcp

Pi extension that exposes MCP through two tools:

- `list_mcp_tools` — enumerates all MCP tools (shows first 20 inline, overflows full list to a temp file)
- `call_mcp` — runs JavaScript in a sandbox and lets the script call MCP servers

It also adds a `/mcp` command for status, enable/disable, reconnect, and auth setup.

## Why?

This was an experiment to see if there is an efficiency benefit of allowing a coding agent interface with
MCP in a way that allows composition.  See [this blog post](https://lucumr.pocoo.org/2025/8/18/code-mcps/).

The actual findings are that with how MCP works today, such efficiency gains are not useful.  On the other
hand an MCP server that uses code internally can be very helpful.  See for
instance an [example MCP server](github.com/mitsuhiko/google-workspace-mcp) that
uses a JavaScript environment to call Google services.  That one actually performs as well as a similar
skill does.

## Configuration files

Loaded in merge order (later overrides earlier):

1. `~/.pi/agent/mcp.json`
2. `~/.pi/agent/.mcp.json`
3. `<cwd>/.pi/mcp.json`
4. `<cwd>/.mcp.json`

You can override with `--mcp-config /path/to/file.json`.

## `list_mcp_tools`

Parameters:

- `query` (optional): case-insensitive text match, or regex via `/pattern/flags`

The tool always shows the first 20 matches inline. If more matches exist, it writes the full list to a temp `.tsv` file so the agent can grep/rg it.

Each listed MCP tool includes a compact schema signature, with required fields marked by `*` and optional fields in brackets.

Only currently enabled MCP tools are listed.

## `/mcp` command

Use `/mcp` to manage MCP from interactive mode:

- `/mcp` — opens an interactive select menu (status, reconnect, auth, and per-server tool toggles)
- `/mcp status` — show server connection/auth state + enabled/disabled counts
- `/mcp enable <server> <tool|all>` — enable a specific MCP tool (or all tools for server)
- `/mcp disable <server> <tool|all>` — disable a specific MCP tool (or all tools for server)
- `/mcp reconnect [server]` — reconnect one/all servers and refresh metadata
- `/mcp auth <server>` — trigger auth setup flow

Tool enable/disable policies are persisted in:

- `~/.pi/agent/mcp-tool-policies.json`

### Auth behavior

- **OAuth flow (standard MCP auth)**
  - `/mcp auth <server>` starts an OAuth browser login flow with localhost callback (for URL-based servers).
  - received tokens are stored in:
    `~/.pi/agent/mcp-oauth/<server>/tokens.json`
  - then the server is reconnected.
  - if a server's auth metadata does **not** support dynamic client registration, `/mcp auth` falls back to bearer setup for the current session (for GitHub Copilot MCP, it will try `gh auth token` automatically).
- **Bearer servers (`auth: "bearer"` or bearer token config)**
  - if `bearerTokenEnv` is configured, `/mcp auth <server>` lets you paste a token into that env var for the current pi process.
  - if no `bearerTokenEnv`, it stores token in memory for the current session.

For OAuth servers that require pre-registered clients, you can provide:

- `oauthClientId`
- `oauthClientSecret` (optional)
- `oauthClientMetadataUrl` (optional)
- `oauthTokenEndpointAuthMethod` (optional)

in the server config entry.

## `call_mcp`

`call_mcp` takes JavaScript code only (plus optional timeout/state reset). Prefer batching: solve each user task in one script and use `Promise.all` for independent calls. Inside the script:

- `await call(server, tool, args)`
- `await readResource(server, uri)`
- `listTools(query?)`
- `servers` (array of configured server names)
- `tools` (map of server -> tool names)
- `resources` (map of server -> resources)
- `state` (persistent mutable object across calls)

Only tools currently enabled in MCP policy are visible/callable from `call_mcp`.

`call(server, tool, args)` throws on MCP tool errors (instead of returning nested `isError`) and includes parameter hints from schema. It also attempts one snake_case → camelCase retry for validation errors.

Example:

```js
const screenshots = await call("chrome-devtools", "take_screenshot", { format: "png" });
const repos = await call("github", "search_repositories", { query: "pi-mono" });

return {
  screenshot: screenshots,
  repos,
  knownServers: servers,
  firstChromeTools: tools["chrome-devtools"]?.slice(0, 10)
};
```