Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicobailon/pi-mcp-adapter/llms.txt

Use this file to discover all available pages before exploring further.

​
Configuration File Location

Pi MCP Adapter looks for server configurations in the following locations:
​
~/.pi/agent/mcp.json
string
Global configuration - Default location for user-wide MCP server settings
​
.pi/mcp.json
string
Project configuration - Project-specific servers that override global settings
Project configurations (.pi/mcp.json) take precedence over global configs and imported servers.

​
Basic Structure

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "some-mcp-server@latest"]
    }
  },
  "settings": {},
  "imports": []
}

​
Server Configuration Fields

​
Stdio Transport

For servers that communicate via standard input/output:
​
command
string
required
The executable command to run the MCP server
{
  "command": "npx"
}
​
args
string[]
Command-line arguments passed to the executable
{
  "args": ["-y", "chrome-devtools-mcp@latest"]
}
​
env
object
Environment variables for the server process. Supports ${VAR} interpolation.
{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "DEBUG": "true"
  }
}
​
cwd
string
Working directory for the server process
{
  "cwd": "/path/to/project"
}

​
HTTP Transport

For servers that communicate over HTTP (uses StreamableHTTP with SSE fallback):
​
url
string
HTTP endpoint for the MCP server
{
  "url": "https://api.example.com/mcp"
}
​
headers
object
Custom HTTP headers to include in requests
{
  "headers": {
    "X-Custom-Header": "value"
  }
}
​
auth
enum
Authentication method for HTTP servers
  • "bearer" - Bearer token authentication
  • "oauth" - OAuth authentication
See Authentication for details.

​
Lifecycle Management

​
lifecycle
enum
default:"lazy"
Controls when the server connects and disconnects
  • "lazy" (default) - Connect on first use, disconnect after idle timeout
  • "eager" - Connect at startup, no auto-reconnect on failure
  • "keep-alive" - Connect at startup, auto-reconnect with health checks
{
  "lifecycle": "lazy"
}
1

Lazy (Default)

Servers don’t connect at startup. They connect on the first tool call and disconnect after the idle timeout period. Metadata is cached so search/describe work without live connections.Best for: Most servers, especially those you don’t use frequently
2

Eager

Servers connect at Pi startup but don’t auto-reconnect if the connection drops. No idle timeout by default (set idleTimeout explicitly to enable).Best for: Servers you want ready immediately but don’t need constant uptime
3

Keep-alive

Servers connect at startup and automatically reconnect via health checks. No idle timeout.Best for: Critical servers you always need available
​
idleTimeout
number
default:"10"
Minutes of inactivity before disconnecting (overrides global setting). Set to 0 to disable.
{
  "idleTimeout": 15
}

​
Resource Handling

​
exposeResources
boolean
default:true
Expose MCP resources as callable tools
{
  "exposeResources": true
}

​
Direct Tool Registration

​
directTools
boolean | string[]
default:false
Register tools individually instead of through the proxy
  • true - Register all tools from this server
  • ["tool_a", "tool_b"] - Register only specific tools (use original MCP names)
  • false - Use proxy only (default)
See Settings for more details on direct tools configuration.
{
  "directTools": ["search_repositories", "get_file_contents"]
}

​
Debugging

​
debug
boolean
default:false
Show server stderr output for debugging
{
  "debug": true
}

​
Complete Examples

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "debug": false
    }
  }
}
npx-based servers are automatically optimized to run as direct binaries, bypassing the ~143 MB npm parent process.

​
Next Steps

Global Settings

Configure toolPrefix, idleTimeout, and directTools defaults

Authentication

Set up OAuth and bearer token authentication

Import Configs

Import existing configs from Cursor, Claude Desktop, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us