MCP servers and interactive UI

Server connections, tool exposure, configuration files, A2UI, and MCP Apps.

MCP servers provide tools and, in some cases, interactive applications. Settings → MCP servers lists catalog services and custom servers in one section.

Connect a service#

Open MCP servers → Servers → +. /connect opens the same area.
Select a catalog service or Your own server.
Choose the available user/project scope.
Complete authorization or enter credentials in the connection form.
Check the connection state and tool list.

Catalog services include Linear, GitHub, Slack, Notion, Sentry, Atlassian, and Figma. Authorization uses the service's browser flow or a token, depending on the connector. A fallback authorization link is shown when applicable.

Project-scoped configuration requires a trusted project. Token handling and service permissions depend on the connection type; review them before enabling tools that modify external data.

Custom servers#

A custom server can use an HTTP URL or a local command. Enter the address, or the executable and arguments, with the required headers/environment values.

For command-based servers, the executable must be available to the desktop backend. Its PATH can differ from a terminal shell; an absolute executable path avoids that dependency.

URL checks can return an authentication requirement before sign-in. A command reachability check locates the executable but does not necessarily start it.

Tool exposure#

Mode	Behavior
Direct	Declare each tool in the model's tool list.
Codemode	Make tools available through the code-based interface.
Deferred	Load tools through discovery/search rather than exposing all initially.

Exposure controls how tools reach the model, not the permissions held by the server. Changing exposure reloads the session as required.

Edit a server or configuration file#

Use a server's Edit action to change its connection details. The form previews the JSON to be written. Save/reconnect, then check the resulting state.

MCP server editor with command, environment, and exposure settings.

The Configuration tab lists the user ~/.pi/agent/mcp.json and project .pi/mcp.json. Edit here validates JSON before saving. External-editor and file-manager actions use the desktop integration.

Supported credential workflows store resolver commands instead of raw secrets. See Credential storage.

Interactive interfaces#

pi-kit supports these interface types in the transcript:

A2UI: a tool returns declarative operations rendered by the host.
MCP App: a server supplies an HTML application resource displayed in a sandboxed frame.
Input requests: a tool or extension asks for confirmation, a selection, text, or another response.

The host frame identifies the interface's source. Actions can call tools or return context to the conversation, depending on the example/server.

Examples#

The repository contains a2ui-failing-specs and mcp-app-server. Their READMEs describe the extension installation and server configuration.

A command-based MCP entry has this shape:

{
  "mcpServers": {
    "issues": {
      "command": "node",
      "args": ["/absolute/path/to/server.mjs"],
      "exposure": "direct"
    }
  }
}

Replace the path with the server file and ensure Node is reachable by the backend. Reload the connection, then request the example tool. The included issue server is a demonstration, not a production issue-tracker connection.