PI 1.4 includes built-in MCP support. PiLot Studio 3.0 adds a management panel on top of it: you can see which servers are configured, whether they are connected, which tools they expose, and how those tools reach the model.

Configuration files

MCP servers live in JSON files that the Pi CLI also reads:

Scope	File	Loads when
User / global	`<agentDir>/mcp.json` (default `~/.pi/agent/mcp.json`)	Always.
Project	`<workspace>/.pi/mcp.json`	Only after the workspace is trusted.

Both use a top-level mcpServers object. A project entry can either define a new server or override a global server's enabled, exposure, or toolExposure fields without repeating its command or URL.

PiLot Studio never keeps MCP servers in a separate database. If you edit the JSON by hand, the panel reflects it after a refresh.

The MCP Servers tab

Open the tab with the plug icon or press 0.

Each card shows:

the server name and transport (stdio command or HTTP URL),
a scope badge: user, project, extension, or user + project override,
live connection state: connected, connecting, needs sign-in, disconnected, failed, or disabled,
the tools reported by pi mcp list --json,
any project override note,
an error message when the config entry is malformed.

The toolbar lets you search servers, refresh the list, add a server, and open either config file. Open main mcp.json opens the global file; Open project mcp.json opens the workspace file. Both create the file if it does not exist.

If the workspace is not trusted, a banner explains that project configuration is being ignored.

Adding a server

Choose + Add server and fill in the form.

Field	Used for
Name	Required, letters/numbers/`-`/`_`.
Scope	Global or project (`--local`).
Transport	`stdio` or HTTP.
Command	The executable for stdio, for example `npx`.
Arguments	One per line.
Environment	One `KEY=value` per line for stdio.
Working directory	Optional stdio `--cwd`.
URL	The MCP endpoint for HTTP.
Headers	One `Header: value` per line.
Bearer token env var	Read the token from this environment variable instead of storing it.
OAuth client ID / secret	Optional overrides for an OAuth-protected server.
Description	A short note shown on the card.
Exposure	How tools reach the model (see below).

Adding a server delegates to the Pi CLI (pi mcp add), so the resulting file uses PI's schema and remains usable from the terminal.

Exposure modes

Exposure is set per server, not globally.

Mode	What the model sees	Best for
codemode	Tools are callable from codemode scripts and hidden from the direct tool list.	Servers with many tools or multi-step workflows. This is the default.
deferred	The model searches with `tool_search`; the selected tool is exposed for the next call.	Large catalogs where direct calls are still preferred after discovery.
direct	Tools are declared like built-in tools.	A small set of frequently used tools.
hidden	The server is registered but unreachable by the model.	Keeping configuration without allowing use.

Change exposure from the server card, or per tool through toolExposure in mcp.json. The effective exposure is shown in the tool chip's tooltip.

OAuth servers

If a server reports needs sign-in, choose Sign in. PiLot Studio runs pi mcp login <name> --timeout 300 and waits for the browser flow. Sign out runs pi mcp logout and deletes the stored credential.

The CLI owns the OAuth token store, so a login completed here also works in the terminal.

Codemode settings

Codemode lets the model write short TypeScript scripts that call tools, instead of declaring every tool in the prompt. Open Preferences → MCP & Codemode.

Setting	Default	What it does
Auto-enable Codemode	On	When a server with `codemode` exposure connects, activate the codemode tool. Stored as `autoEnableCodemode` in the main `mcp.json`.
Enable Codemode by default	Off	Adds `+codemode` to the global `defaultTools`, so new sessions start with codemode available. A project-level `defaultTools` still layers on top.
Codemode mode	`on`	`on` keeps declared tools declared and explains how to call them from scripts; codemode lists only undeclared tools. `only` hides all tools from the model and routes every call through codemode.
Inline tool budget	`3000`	Estimated tokens (characters ÷ 4) the codemode description may spend on TypeScript declarations. Tools that do not fit are found with `searchTools()`. `0` lists only namespaces.

Codemode values are merged into PI's global settings.json; autoEnableCodemode lives beside mcpServers in the main mcp.json. The panel labels each effective value with its source:

Global — set in the global file.
Project — set by a trusted project's .pi/settings.json or .pi/mcp.json.
Default — PI's built-in default.

Edits from the panel write the global files. A project override still wins in that workspace, and the panel says so. Changes apply to new sessions.

Light Mode skips PI's MCP, codemode, and tool-search extension factories. If Light Mode is on, MCP tools are not available even if servers are configured.

Project trust

PI 1.4 gates project-local .pi resources, MCP servers, packages, and extensions behind project trust. PiLot Studio asks only when the workspace actually contains a gated resource; a plain repository opens without a prompt.

The choices are:

Trust — persist the decision.
Trust (this session only) — allow for this window.
Do not trust — persist a denial.
Do not trust (this session only) — deny for this window.

Cancelling the prompt resolves to untrusted. Decisions are stored in PI's trust.json, so trusting a workspace in the Pi CLI trusts it here too, and the reverse.

Editing the JSON directly

The panel is a convenience, not a separate configuration layer. A minimal global mcp.json looks like this:

{
	"mcpServers": {
		"filesystem": {
			"command": "npx",
			"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"],
			"exposure": "codemode"
		}
	},
	"autoEnableCodemode": true
}

An HTTP server uses url instead of command/args:

{
	"mcpServers": {
		"remote": {
			"type": "http",
			"url": "https://example.com/mcp",
			"exposure": "deferred"
		}
	}
}

For an authenticated remote server, prefer the form's Bearer token env var field so the token stays in the environment instead of the config file. Headers can also be set directly when the server uses a non-bearer scheme.

PiLot Studio validates the fields it displays and reports malformed entries instead of hiding the whole file. PI validates the full schema again when it connects.

Troubleshooting MCP

Server not listed. Check the file location and JSON syntax. Project servers require trust; the panel shows a trust banner when they are ignored.
Needs sign-in. Use Sign in. If the browser flow times out, run pi mcp login <name> in a terminal and refresh.
Connected with no tools. The server may expose no tools, or tool discovery may have failed. Check its error on the card and the server's own logs.
Project override wins. The panel shows which values come from the project. Edit .pi/mcp.json or untrust the workspace to change them.
Codemode is not active. Confirm a codemode-exposed server is connected and Auto-enable Codemode is on, or add +codemode to defaultTools.
Everything disappeared in Light Mode. That is expected; Light Mode does not load MCP or codemode.