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.

​
Overview

Each MCP server is configured as an entry in the mcpServers object in your mcp.json file. The ServerEntry interface defines all available configuration options.

​
Configuration Structure

{
  "mcpServers": {
    "server-name": {
      // ServerEntry fields here
    }
  }
}

​
Transport Configuration

MCP servers can use either stdio (local process) or HTTP transport.

​
Stdio Transport

For local servers that communicate via stdin/stdout:
​
command
string
The executable to run (e.g., "npx", "node", "python", or an absolute path).
​
args
string[]
Command-line arguments for the server process.Example:
"args": ["-y", "chrome-devtools-mcp@latest"]
​
env
Record<string, string>
Environment variables for the server process. Supports ${VAR} interpolation from the parent process environment.Example:
"env": {
  "API_KEY": "${MY_API_KEY}",
  "DEBUG": "true"
}
​
cwd
string
Working directory for the server process. Defaults to the current directory.

​
HTTP Transport

For remote servers accessed via HTTP:
​
url
string
The HTTP endpoint URL. The adapter attempts StreamableHTTP transport first, then falls back to SSE if the server doesn’t support it.Example:
"url": "https://mcp.example.com"
​
headers
Record<string, string>
Custom HTTP headers to send with requests.Example:
"headers": {
  "X-API-Version": "2024-01-01",
  "User-Agent": "Pi MCP Adapter"
}

​
Authentication

​
auth
'oauth' | 'bearer'
Authentication method for HTTP servers.
  • "oauth" - Uses OAuth tokens from ~/.pi/agent/mcp-tokens/<server-name>.json
  • "bearer" - Uses static bearer tokens from bearerToken or bearerTokenEnv
​
bearerToken
string
Static bearer token for authentication. Not recommended for production (use bearerTokenEnv instead).Example:
"bearerToken": "your-secret-token"
​
bearerTokenEnv
string
Name of an environment variable containing the bearer token. More secure than bearerToken.Example:
"bearerTokenEnv": "API_SERVER_TOKEN"
The adapter reads process.env.API_SERVER_TOKEN at runtime.

​
Lifecycle Management

​
lifecycle
'lazy' | 'eager' | 'keep-alive'
default:"lazy"
Controls when the server connects and how it handles disconnections.
  • lazy (default) - Don’t connect at startup. Connect on first tool call. Disconnect after idle timeout.
  • eager - Connect at startup but don’t auto-reconnect if the connection drops. No idle timeout by default.
  • keep-alive - Connect at startup. Auto-reconnect via health checks. No idle timeout.
​
idleTimeout
number
Minutes of inactivity before disconnecting the server. Overrides the global settings.idleTimeout.
  • Set to 0 to disable idle timeout for this server
  • Only applies to lazy and eager modes (keep-alive servers never idle out)
Example:
"idleTimeout": 5  // Disconnect after 5 minutes of inactivity

​
Resource Handling

​
exposeResources
boolean
default:"true"
Whether to expose MCP resources as callable tools.When true, each resource becomes a tool named get_<resource_name> that reads the resource content.Example:
"exposeResources": false  // Don't create tools for resources

​
Direct Tool Registration

​
directTools
boolean | string[]
default:"false"
Controls whether tools from this server are registered as individual Pi tools instead of being accessed through the mcp() proxy.
  • true - Register all tools from this server as direct Pi tools
  • ["tool_a", "tool_b"] - Register only the specified tools (use original MCP names, not prefixed names)
  • false or omitted - Proxy only (default)
Direct tools appear in the agent’s tool list alongside builtins like read and bash. This costs ~150-300 tokens per tool but eliminates the need for search calls.Examples:
// Register all tools
"directTools": true

// Register specific tools only
"directTools": ["take_screenshot", "navigate"]

// Proxy only (default)
"directTools": false
Direct tools register from the metadata cache at startup. On the first session after configuring directTools, the cache may not exist yet. Run /mcp reconnect <server> and restart Pi to populate the cache.

​
Debugging

​
debug
boolean
default:"false"
Show server stderr output in the terminal. Useful for troubleshooting server startup or runtime issues.By default, server stderr is suppressed to keep the terminal clean.Example:
"debug": true  // Show stderr from this server

​
Complete Examples

​
Stdio Server (npx)

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "lifecycle": "lazy",
      "idleTimeout": 10
    }
  }
}

​
Stdio Server (local script)

{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "NODE_ENV": "production",
        "API_KEY": "${MY_API_KEY}"
      },
      "cwd": "/path/to/project"
    }
  }
}

​
HTTP Server with Bearer Token

{
  "mcpServers": {
    "api-server": {
      "url": "https://api.example.com",
      "auth": "bearer",
      "bearerTokenEnv": "API_SERVER_TOKEN",
      "headers": {
        "X-API-Version": "2024-01-01"
      }
    }
  }
}

​
HTTP Server with OAuth

{
  "mcpServers": {
    "github": {
      "url": "https://mcp.github.com",
      "auth": "oauth"
    }
  }
}
Tokens are read from ~/.pi/agent/mcp-tokens/github.json.

​
Keep-Alive Server

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "postgres-mcp"],
      "lifecycle": "keep-alive",
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

​
Server with Direct Tools

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

​
Debug Mode

{
  "mcpServers": {
    "broken-server": {
      "command": "node",
      "args": ["server.js"],
      "debug": true
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us