pi-mcp-client 0.3.3 → 0.5.0

package/docs/authentication.md

@@ -0,0 +1,175 @@
+# Authentication
+
+[Back to the README](../README.md)
+
+You manage authentication through `/mcp login` and `/mcp logout`. The assistant
+can't initiate an OAuth login: only your explicit login command opens the browser.
+For externally managed bearer tokens, use
+[headers and secret commands](configuration.md#secret-commands) instead.
+
+## Sign in with OAuth
+
+Add the HTTP server, then log in:
+
+```text
+/mcp add --scope global slack https://mcp.slack.com/mcp
+/mcp login slack
+```
+
+Login uses the effective server definition (the trusted project override, if
+present; otherwise the global definition) and starts the SDK's OAuth discovery
+and authorization flow. It doesn't change configuration files. Adding a server
+still doesn't connect or open a browser.
+
+HTTP servers use automatic authentication by default:
+
+- Configured Authorization headers take precedence over OAuth.
+- Otherwise, connections reuse stored OAuth tokens when available. The SDK
+  handles authentication challenges and refreshes existing grants.
+- Without a grant, an authentication challenge asks you to run `/mcp login`.
+  Discovery and tool calls never register a new client or open a browser.
+- A missing or locked keyring doesn't block public servers. If the server
+  requires OAuth, an unavailable keyring is an error; no credentials are stored
+  outside the OS credential store.
+
+The `oauth` configuration field and `--oauth` switch aren't supported. Remove
+these from existing definitions and commands; HTTP authentication is automatic.
+
+If the server uses an Authorization header, login asks you to remove that header
+before switching to OAuth; it never replaces existing header credentials.
+Stdio servers manage their own authentication and don't support OAuth login.
+
+The extension supports public clients with dynamic registration or a
+pre-registered client ID. Both use PKCE and a loopback callback at
+`http://127.0.0.1:19847/callback` by default. Normal login opens a local listener
+that your browser must be able to reach.
+
+Authentication times out after two minutes; you can cancel it with Escape in the
+terminal UI. Explicit login always starts a fresh authorization flow, even if a
+refresh token is already stored. The browser callback page identifies **Pi MCP
+Client** and asks you to return to Pi; receiving a callback doesn't yet mean the
+token exchange succeeded.
+
+OAuth tokens and client registrations are stored in the operating system
+credential store, bound to the server URL, configured client ID (if any), and
+authorization-server issuer. There is no plaintext credential fallback. PKCE
+verifiers and callback state stay in memory. Linux requires a working Secret
+Service/keyring session.
+
+### Upgrade from earlier versions
+
+Credentials now use an identity based only on the server URL and optional client
+ID. Earlier credential-store entries aren't migrated or deleted. Run
+`/mcp login <server>` again after upgrading; revoke old grants at the service if
+needed. Changing scopes or the callback port doesn't select a different store.
+
+## Use a pre-registered client
+
+For a server without dynamic registration, register a **public/native** client
+with the service, using the exact callback URL and token endpoint authentication
+method `none`. Then configure its client ID:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauthClientId": "${EXAMPLE_OAUTH_CLIENT_ID}"
+    }
+  }
+}
+```
+
+Run `/mcp reload`, then `/mcp login example`. The configured ID is used for login,
+token refresh, and revocation; the extension never falls back to dynamic
+registration if it is rejected. `/mcp get example` identifies the client as
+pre-registered without printing the ID.
+
+Changing the client ID selects separate credentials and requires a new login.
+Log out before changing or removing the ID if you want to delete its old
+credentials. After the first successful grant, a pre-registered client is pinned
+to its authorization-server issuer. If that issuer changes, verify the server
+configuration before logging out and logging in again to trust the replacement.
+
+## Set scopes and callback ports
+
+Configure scopes and a callback port in the server definition:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauthScopes": ["read", "write"],
+      "oauthCallbackPort": 19848
+    }
+  }
+}
+```
+
+Or set them when adding the server:
+
+```text
+/mcp add --scope global --oauth-scope read --oauth-scope write --oauth-callback-port 19848 example https://mcp.example.com/mcp
+```
+
+The callback becomes `http://127.0.0.1:19848/callback`. Pre-registered clients must
+allow that exact URL. The listener stays bound to loopback; arbitrary callback
+hosts and paths aren't supported. If the port is occupied, choose another port or
+use manual login.
+
+Scopes are case-sensitive OAuth tokens, each up to 256 characters, without spaces,
+quotes, or backslashes. Omit `oauthScopes` to retain SDK/server-driven selection;
+an empty array is rejected. The SDK may also request `offline_access` when the
+service advertises refresh-token support. Requested scopes aren't a guarantee of
+granted permissions or a per-tool permission policy.
+
+After changing these options, run `/mcp reload`, then `/mcp login example`.
+Changing configuration never starts authorization or revokes existing grants.
+Scopes and callback ports don't select separate credential stores: definitions
+sharing a URL and client ID still share credentials. Explicit login renews a
+dynamic registration when its requested options change. `/mcp get example` shows
+the requested scopes and callback address without connecting.
+
+## Sign in remotely or without launching a browser
+
+When Pi runs over SSH, or you don't want it to launch a browser, use:
+
+```text
+/mcp login example --no-browser
+```
+
+1. Open the authorization URL shown in Pi's interactive dialog in your browser.
+2. Complete sign-in. The browser may show a connection error at the loopback
+   callback address; this is expected when the browser and Pi run on different
+   machines.
+3. Copy the full callback URL from the browser's address bar and paste it into
+   the **Callback URL** dialog in Pi, not into chat or a slash command.
+
+Manual login doesn't open a browser or bind a callback port. The extension
+validates the callback address, state, and authorization response before
+exchanging the code. It doesn't write authorization URLs or pasted callbacks to
+session entries, catalogs, notifications, or logs. Treat the callback URL as
+sensitive; your browser history and clipboard may still contain it.
+
+`--no-browser` still requires an interactive UI and an available OS credential
+store. It isn't unattended authentication: print and JSON modes refuse OAuth
+login. Use externally managed bearer headers for unattended access. Confidential
+clients requiring a client secret aren't supported yet.
+
+## Sign out
+
+Run `/mcp logout <server>` to remove stored tokens and client registrations. Logout
+also closes connections and deactivates tools for OAuth servers sharing
+the same URL and configured client ID, since they share credentials. Configuration
+and enabled state stay unchanged. Disabled servers accept logout too. Header and
+server-managed credentials remain untouched.
+
+Local removal happens before a bounded attempt to revoke tokens at the original
+authorization server. The result distinguishes accepted revocation, unsupported
+revocation, and unconfirmed revocation. When revocation isn't confirmed, remove the
+grant at the service if needed. Repeating logout is safe. Other running Pi sessions
+may need to reconnect; logout cannot recall requests already sent to a server.
+
+Removing a server definition doesn't remove its credentials. Log out before
+[removing the definition](commands.md#add-and-remove-servers) if you want both.

package/docs/behavior.md

@@ -0,0 +1,114 @@
+# Behavior and permissions
+
+[Back to the README](../README.md)
+
+This page explains how the extension manages state and displays results. For the
+assistant's tool-call interface, see the [tool reference](tool-reference.md).
+
+## Sessions
+
+- Active tools accumulate rather than rotating with each prompt.
+- Resume and branch navigation restore tools activated through `mcp_tools` on
+  the selected branch. Discovery results never restore tools.
+- Compaction retains the acquired tool set. New sessions start fresh.
+- Pi uses native deferred loading where supported by the model and provider.
+  Other providers receive the expanded tool list normally.
+- Discovery respects server filters; activation also respects Pi's tool exclusions.
+  An explicit tool allowlist must include both `mcp_tools` and the native tools
+  the assistant needs to load.
+
+## Resource snapshots
+
+Resource reads never start OAuth login, follow links in resource bodies, or
+subscribe to live updates. Repeated reads fetch fresh content; earlier results
+stay as snapshots. Resuming a session or navigating its branches doesn't re-read
+resources. Watches have their own
+[memory-only lifecycle](commands.md#watch-resource-changes) and never fetch content
+automatically.
+
+Resource content and selected metadata, including URIs, become session data and
+may be sensitive. [Private spill files](troubleshooting.md#large-results) can also
+contain sensitive data and aren't automatically deleted.
+
+## Discovery and caching
+
+Connections start on demand, never while the extension factory loads. A search
+without the requested cached metadata contacts configured servers, with at most
+four server discoveries in flight. A server-scoped search only contacts that
+server. Activation discovers only the servers named by its identifiers, with the
+same concurrency bound. Failed servers are reported as unavailable, not mistaken
+for an empty catalog.
+
+Tool catalogs are cached privately under `~/.pi/agent/cache/pi-mcp-client/`, keyed
+by server configuration and working directory. Disk caches expire after 24 hours.
+They contain tool metadata, not configured credentials. Cached tool-only discovery
+and activation need no connection; invocation refreshes the live catalog before
+calling the tool.
+
+Resource metadata, including template catalogs, is held only in memory for up to
+five minutes, not written to the tool catalog cache. Mixed discovery therefore
+may connect even when tools are cached on disk. Resource-list notifications,
+disconnection, and explicit refresh invalidate resource metadata without reading
+content. Tool and resource catalog failures are reported independently; healthy
+candidates remain available. The SDK handles pagination. Resource catalogs are
+limited to 10,000 entries and 4 MiB of descriptor data; oversized catalogs fail
+rather than silently returning a partial list. Reads bypass the SDK content cache.
+Connections remain open until shutdown or an explicit lifecycle action such as
+reconnection or configuration reload.
+
+When a connected server reports a tool-list change, the extension invalidates its
+memory and disk catalogs. The next discovery or activation fetches the current
+list, including new or removed tools. Notifications don't replace active tool
+definitions: the assistant must activate changed schemas again before use. Calls
+validate the live catalog before execution and refuse removed or changed tools.
+Disconnected, cache-only searches can't receive notifications and still use the
+24-hour disk-cache expiry.
+
+## Result display
+
+The UI labels discovery calls **mcp discover**, activation calls **mcp activate**,
+resource reads **mcp read**, and argument completions **mcp complete**.
+
+Discovery rows show `○` for inactive candidates and `●` for already active tools,
+without a status suffix. These reflect the state when discovery runs; earlier
+results don't update retroactively. Activation results use `✔︎` for success and
+`✘︎` for failure. Descriptions stay gray; identifiers remain prominent.
+
+Exact and template reads use the same compact status row:
+
+```text
+mcp read
+ ✔︎ warehouse · schema://tables/events
+```
+
+Expand a tool result to see JSON objects and arrays formatted with two-space
+indentation and syntax highlighting. Explicit JSON resource MIME types (including
+`application/*+json`) and structured content identify JSON without guessing.
+Other explicit MIME types stay plain text; unlabeled text is checked for JSON.
+
+Formatting changes only the display, not the response sent to the assistant.
+Invalid or truncated JSON stays plain text. Results that would exceed formatting
+limits also stay plain text. Resource-link MIME types describe the linked content,
+not the displayed link label. Supported images use the existing result display;
+see [large results](troubleshooting.md#large-results) for size limits.
+
+## Trust and permissions
+
+Only load configuration you trust. Server executables and secret commands run
+with your user permissions; trusted project configuration can replace global
+connections and settings.
+
+Server metadata and resource content are untrusted data. Discovery never
+activates tools. Explicit activation exposes schemas but doesn't approve tool
+side effects or provide per-call confirmation. Use tool filters and Pi permission
+extensions for additional controls. Cancelling a call doesn't guarantee that the
+server rolled back its effects. The extension doesn't retry failed tool
+invocations; verify an interrupted operation's outcome before trying again.
+
+`includeTools` and `excludeTools` apply only to tools, not resources. Keeping
+`mcp_tools` available permits resource reads from enabled servers, subject to the
+server's authorization. `kind: "tools"` filters one search; it isn't an access
+restriction. Disable a server to prevent all access, or exclude `mcp_tools` through
+Pi's tool restrictions to prevent discovery and resource operations. Already active
+native tools have their own tool restrictions. Per-resource permission policies
+aren't implemented.

package/docs/commands.md

@@ -0,0 +1,171 @@
+# Commands
+
+[Back to the README](../README.md)
+
+These are commands **you run in Pi**, not tools the assistant calls. Use them to
+manage servers, inspect capabilities, and watch resource changes. The assistant's
+separate interface is documented in the [tool reference](tool-reference.md).
+
+## Command reference
+
+| Command | Purpose |
+| --- | --- |
+| `/mcp`, `/mcp list`, `/mcp status` | Show a server status matrix with catalog and loaded-tool counts. |
+| `/mcp add --scope <scope> [options] <server> <url>` | Save an HTTP server without connecting. For stdio, use `<server> -- <command> [args...]`. |
+| `/mcp remove --scope <scope> <server>` | Remove a definition from the selected scope, retaining credentials. |
+| `/mcp get <server>` | Inspect status and configuration, including disabled servers. Connection values are hidden. |
+| `/mcp tools <server>` | Browse the server's tools and inspect descriptions without activating tools. |
+| `/mcp reload` | Apply configuration changes without restarting Pi. |
+| `/mcp enable <server>` | Enable a server in its effective configuration file. |
+| `/mcp disable <server>` | Disable a server, close its connection, and deactivate its tools. |
+| `/mcp login <server> [--no-browser]` | Authenticate an HTTP server without changing its configuration; optionally paste the callback URL in an interactive dialog. |
+| `/mcp logout <server>` | Remove local OAuth credentials and attempt remote revocation, including for disabled servers. |
+| `/mcp reconnect <server>` | Replace a connection and refresh its catalog. |
+| `/mcp refresh <server>` | Refresh tool and resource metadata without reading resources or loading additional tools. |
+| `/mcp subscribe <server> <uri>` | Watch changes to one exact resource URI without fetching content. |
+| `/mcp unsubscribe <server> <uri>` | Stop watching one resource. |
+| `/mcp subscriptions` | List active resource watches and their change markers. |
+
+See [Authentication](authentication.md) for login and logout procedures, and
+[Apply changes](configuration.md#apply-changes) for reload behavior.
+
+## Inspect servers and tools
+
+The `/mcp` status matrix distinguishes idle (`○`), connected (`●`), connecting
+(`▶︎`), disabled (`○`), and failed (`✘︎`) servers. Idle is normal: connections open
+on demand. A dash (`—`) means the catalog hasn't been fetched, not that the server
+has no tools. The **Loaded** column counts tools currently active for the
+assistant.
+
+Use `/mcp get <server>` to check the effective transport, protocol, filters,
+and connection status without connecting or running secret commands. Connection
+values—including commands, arguments, URLs, headers, and environment variables—
+are hidden because any of them can contain credentials. Authentication status
+shows whether OAuth tokens are stored, not whether they are valid. A locked or
+unavailable credential store is reported separately from missing tokens. Header
+and stdio credentials are identified as externally managed; inspection never
+executes them.
+
+Use `/mcp tools <server>` to fetch the current catalog and browse a scrollable
+list. Rows show tool names and descriptions, trimmed to the terminal width with
+an ellipsis. Select a tool to see a multiline signature and parameter details,
+with each parameter in a separate paragraph. Browsing respects your include and
+exclude filters and doesn't activate tools or add their schemas to the assistant's
+context. This command requires an interactive UI.
+
+Refreshing a catalog doesn't replace active tool definitions. After a schema
+change, ask the assistant to activate the exact tool again. See
+[tool changes and caching](behavior.md#discovery-and-caching). Failed tool calls
+aren't retried automatically; verify whether an interrupted operation completed
+before trying again.
+
+## Enable and disable servers
+
+Use `/mcp disable <server>` or `/mcp enable <server>` to change the `disabled`
+option without editing JSON. The command reports which scope changed: the trusted
+project's `.mcp.json` if it defines the server, otherwise the global
+`~/.pi/agent/mcp.json`. Untrusted project files are neither read nor changed.
+
+Toggles preserve other values, including secret references, and reformat the file
+as indented JSON. Repeating a toggle that's already set leaves the file unchanged.
+Both commands wait for active agent work to finish, then
+[apply the configuration](configuration.md#apply-changes).
+
+Disabling removes the server from discovery and deactivates its tools. Enabling
+doesn't connect, authenticate, or load tools; ask the assistant to discover the
+capabilities you need.
+
+## Add and remove servers
+
+Both commands require an explicit `--scope global` or `--scope project`:
+
+- **Global:** `~/.pi/agent/mcp.json`.
+- **Project:** `.mcp.json` in the current trusted project. Untrusted project files
+  are neither read nor changed.
+
+Add an HTTP server by URL, or a stdio server after `--`:
+
+```text
+/mcp add --scope global docs https://docs.mcp.cloudflare.com/mcp
+/mcp add --scope project local -- node "/path with spaces/server.js"
+```
+
+Put options before the server name. `--transport http` or `--transport stdio` is
+optional; the URL form selects HTTP and the `--` form selects stdio. Arguments
+support single and double quotes and backslash escaping, but are never evaluated
+by a shell. Shell syntax such as `$(...)`, pipes, and globs stays literal. For
+Windows paths with backslashes, single quotes preserve the path verbatim.
+
+| Option | Purpose |
+| --- | --- |
+| `--replace` | Replace the complete definition in the selected scope, or create an override of a same-named definition in the other scope. Existing fields aren't merged. |
+| `--header 'Name: value'` | Add an HTTP header. Repeat for different header names. |
+| `--env KEY=value` | Add a stdio environment override. Repeat for different variable names. |
+| `--oauth-client-id ID` | Use a pre-registered public client. |
+| `--oauth-scope SCOPE` | Request an OAuth scope. Repeat for additional scopes. |
+| `--oauth-callback-port PORT` | Set the loopback callback port. |
+
+Retain environment references rather than typing tokens:
+
+```text
+/mcp add --scope global --header 'Authorization: Bearer ${DOCS_TOKEN}' docs https://mcp.example.com/mcp
+/mcp add --scope global --oauth-client-id '${CLIENT_ID}' service https://mcp.example.com/mcp
+```
+
+Define referenced environment variables before running the command. Validation
+checks the resolved configuration, but saves the references, not their values.
+Secret commands in headers or environment overrides are saved without running
+them. Avoid literal credentials in command input or project files; use
+[environment references and secret commands](configuration.md#secret-commands).
+
+Adding never starts a server, opens a browser, or activates tools. Duplicate names
+in global or trusted project configuration are rejected unless you supply
+`--replace`. Project definitions take precedence; writing a global definition
+doesn't replace a project override. Other server options, such as tool filters,
+remain available by editing the configuration file.
+
+Remove a definition from a specific scope:
+
+```text
+/mcp remove --scope project local
+```
+
+Removal is distinct from disabling and logout: it deletes the selected definition,
+not its OAuth credentials. Run `/mcp logout <server>` first if you also want to
+remove credentials. Removing a project override exposes any same-named global
+definition; the command reports when a definition in the other scope remains.
+Removing a name absent from the selected scope fails without changing either file.
+
+Successful edits [apply immediately](configuration.md#apply-changes). Writes
+preserve unrelated settings, follow existing file symlinks, and replace files
+atomically. New files are private; existing file permissions are preserved. If
+global and project configuration point to the same file, scoped edits are refused
+until you separate them. Empty configuration files are retained rather than deleted.
+
+## Watch resource changes
+
+Subscriptions are explicit user commands, not model-facing tool operations:
+
+```text
+/mcp subscribe warehouse schema://tables/events
+/mcp subscriptions
+/mcp unsubscribe warehouse schema://tables/events
+```
+
+Use an exact absolute URI from discovery, a template read, or a resource link.
+The configured server must support resource subscriptions. The extension uses the
+SDK's negotiated protocol: legacy resource subscriptions or modern filtered
+streams. It never opens the URI as a file or generic URL.
+
+An update marks the watch as changed (`↻`) and shows a UI notification. Repeated
+updates coalesce into that marker until you unsubscribe. No content is fetched,
+no model turn starts, and existing resource results remain unchanged. Ask the
+assistant to read the resource for a new snapshot; unsubscribe and subscribe again
+to reset the change marker.
+
+Watches are memory-only, limited to 50 per server connection, and require an
+interactive UI (TUI or RPC). Repeating a subscribe command is idempotent. Session
+replacement, tree navigation, configuration reload, disconnection, and exit clear
+the affected watches. They are never restored or automatically retried; use
+`/mcp subscriptions` to inspect active watches. Cancellation and connection
+failures can leave an uncertain server-side outcome; cleanup is best-effort.

package/docs/configuration.md

@@ -0,0 +1,150 @@
+# Configuration
+
+[Back to the README](../README.md)
+
+You configure which servers the assistant can access. Add connections to
+`~/.pi/agent/mcp.json`, or `.mcp.json` in a trusted project. For command-based
+setup, see [Add and remove servers](commands.md#add-and-remove-servers).
+
+## Files and transports
+
+The files use the common Claude/Cursor-style `mcpServers` format, not a universal
+MCP configuration standard. VS Code's `servers` format and Codex's TOML format
+aren't supported. `PI_CODING_AGENT_DIR` overrides the global Pi directory.
+Project definitions replace same-named global definitions in full; fields and
+filters aren't merged. Untrusted project files are neither read nor changed.
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "url": "https://mcp.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${DOCS_TOKEN}"
+      }
+    },
+    "local": {
+      "command": "node",
+      "args": ["/absolute/path/to/server.js"],
+      "env": {
+        "DATABASE_URL": "${DATABASE_URL}"
+      }
+    }
+  }
+}
+```
+
+| Field | Purpose |
+| --- | --- |
+| `type` | Optional `stdio` or `http`. If omitted, inferred from `command` or `url`. A conflicting type is rejected. |
+| `command`, `args` | Executable and arguments for a stdio server. No shell is used. |
+| `cwd` | Working directory for stdio; defaults to Pi's current directory. Relative paths resolve there. |
+| `env` | Additional environment variables for stdio. |
+| `url` | Streamable HTTP endpoint; mutually exclusive with `command`. |
+| `headers` | HTTP request headers, including optional bearer authentication. |
+
+Strings in `command`, `args`, `cwd`, `env`, `url`, and `headers` support `${VAR}`
+interpolation. Missing variables prevent that server from connecting.
+
+Only stdio and Streamable HTTP are supported. The extension rejects `type: "sse"`
+and unsupported connection fields rather than silently changing their meaning.
+
+The extension uses `@modelcontextprotocol/client` 2.0.0 and defaults to automatic
+SDK protocol-version negotiation. On stdio, negotiation probes using an additional
+short-lived process. Set `"protocol": "legacy"` if the server requires an explicit
+legacy handshake.
+
+## Secret commands
+
+In **`headers` and stdio `env` values only**, a leading `!` runs a secret-generating
+shell command when the server connects:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "headers": {
+        "Authorization": "!token=$(op read 'op://Private/Example/token') && printf 'Bearer %s' \"$token\""
+      }
+    }
+  }
+}
+```
+
+These two fields also support Pi-style `$VAR` interpolation, `$$` for a literal
+`$`, and `$!` for a literal `!`. Only a leading `!` in the original configuration
+triggers execution; interpolated values and command output never do. Shell
+commands handle their own variable expansion.
+
+Commands use `/bin/sh` on Unix or Pi's shell selection on Windows, inherit Pi's
+process environment, and run in the server's configured `cwd` (the project
+directory by default). They run once per connection, including reconnections,
+not during configuration loading, status display, or cached discovery. Cold
+searches and activations can connect and therefore execute commands. Concurrent
+connection requests share the same resolution.
+
+The extension trims stdout and rejects empty output, nonzero exits, output above
+64 KiB, and resolution taking more than 10 seconds (or a shorter `timeoutMs`).
+Session shutdown cancels pending commands. Cancelling an individual search or
+activation stops waiting but leaves shared connection work running for other
+callers.
+
+The extension discards command stderr and doesn't include resolved secrets in
+errors, session records, or catalog caches. Commands themselves remain responsible
+for avoiding side effects or writing secrets to disk. Only configure commands you
+trust; project configuration still requires project trust.
+
+## Pi-specific options
+
+Put descriptions, authentication choices, filters, and timeouts directly in each
+server definition:
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "url": "https://mcp.example.com/mcp",
+      "description": "Search product documentation",
+      "includeTools": ["get_*", "search_*"]
+    }
+  }
+}
+```
+
+| Field | Purpose |
+| --- | --- |
+| `description` | Short capability description for the assistant's server directory. |
+| `oauthClientId` | Optional pre-registered public client ID. Supports `${ENV_VAR}` interpolation, not secret commands. |
+| `oauthScopes` | Optional array of 1–100 unique OAuth scope tokens to request at login. Omitted scopes use SDK/server defaults. Values are literal, without interpolation. |
+| `oauthCallbackPort` | Optional loopback callback port, from 1 to 65535. Defaults to `19847`. |
+| `disabled` | Prevent this server from connecting or exposing tools and resources. |
+| `includeTools` | Optional allowlist of original MCP tool names; `*` matches any sequence. An empty list exposes no tools. |
+| `excludeTools` | Denylist applied after `includeTools`. |
+| `timeoutMs` | Request timeout, from 100 to 600000 ms. Defaults: 15 seconds for discovery/HTTP requests, 30 seconds for stdio tool calls. |
+| `protocol` | `auto` (default) for SDK protocol-version negotiation, or `legacy` for an explicit legacy handshake. |
+
+OAuth client IDs, scopes, and callback ports require HTTP without an Authorization
+header. HTTP authentication is automatic; remove the obsolete `oauth` field from
+existing definitions. See [authentication](authentication.md).
+
+Every definition must include a `url` or `command`, even when `disabled` is true.
+These options are specific to Pi MCP Client, not standardized MCP connection
+fields. Other clients may reject them when you copy a definition.
+
+Tool filters don't restrict resource reads. See
+[trust and permissions](behavior.md#trust-and-permissions) for access boundaries
+and [authentication](authentication.md) for OAuth setup.
+
+## Apply changes
+
+After editing a file, run `/mcp reload`. The extension validates the new
+configuration before replacing the current setup; invalid configuration leaves
+the previous setup intact. Reload closes connections, which reopen on demand,
+and deactivates tools from changed, removed, or disabled definitions. Unchanged
+active tools remain available.
+
+Server-management commands apply saved changes using the same reconciliation.
+Other running Pi sessions pick up those changes when you reload their MCP
+configuration. See [Commands](commands.md) for toggling, inspecting, adding, and
+removing servers.