add-mcp-server

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add an MCP Server

添加MCP服务器

Add an MCP server configuration to

pi-mcp-adapter

. Determine scope and server type, write the config, and verify the connection.

为

pi-mcp-adapter

添加MCP服务器配置。确定作用域和服务器类型，写入配置并验证连接。

Step 1: Determine Scope

步骤1：确定作用域

Ask the user if not obvious from context:

Scope	Config File	When to Use
Global	`~/.pi/agent/mcp.json`	Server used across all projects
Project	`.pi/mcp.json` (project root)	Server specific to one project

Project-local configs override global ones. Both files use the same format.

如果上下文未明确说明，请询问用户：

作用域	配置文件	使用场景
全局	`~/.pi/agent/mcp.json`	所有项目通用的服务器
项目本地	`.pi/mcp.json` （项目根目录）	仅针对单个项目的服务器

项目本地配置会覆盖全局配置。两种文件使用相同格式。

Step 2: Determine Server Type

步骤2：确定服务器类型

MCP servers connect via stdio (local process) or HTTP (remote URL).

Stdio server — runs a local command:

json

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name@latest"],
      "env": { "KEY": "value" }
    }
  }
}

HTTP server — connects to a URL:

json

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

MCP服务器通过stdio（本地进程）或HTTP（远程URL）连接。

Stdio服务器 — 运行本地命令：

json

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name@latest"],
      "env": { "KEY": "value" }
    }
  }
}

HTTP服务器 — 连接至URL：

json

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

Step 3: Gather Configuration

步骤3：收集配置信息

Collect only what's needed. All fields except

command

url

are optional.

Field	Type	Description
`command`	string	Executable to run (stdio)
`args`	string[]	Command arguments (stdio)
`env`	object	Environment variables (stdio)
`cwd`	string	Working directory (stdio)
`url`	string	Server URL (HTTP)
`headers`	object	HTTP headers (HTTP)
`auth`	`"oauth"` or `"bearer"`	Auth method (HTTP)
`bearerToken`	string	Static bearer token
`bearerTokenEnv`	string	Env var name for bearer token
`lifecycle`	`"lazy"` / `"eager"` / `"keep-alive"`	Connection strategy (default: `lazy` )
`idleTimeout`	number	Minutes before idle disconnect
`debug`	boolean	Show server stderr

Lifecycle modes:

lazy (default) — connects on first tool call, disconnects after idle timeout
eager — connects at session start, no auto-disconnect
keep-alive — connects at start, auto-reconnects if dropped

仅收集必要信息。除

command

url

外，所有字段均为可选。

字段	类型	描述
`command`	字符串	要运行的可执行文件（stdio模式）
`args`	字符串数组	命令参数（stdio模式）
`env`	对象	环境变量（stdio模式）
`cwd`	字符串	工作目录（stdio模式）
`url`	字符串	服务器URL（HTTP模式）
`headers`	对象	HTTP请求头（HTTP模式）
`auth`	`"oauth"` 或 `"bearer"`	认证方式（HTTP模式）
`bearerToken`	字符串	静态Bearer令牌
`bearerTokenEnv`	字符串	存储Bearer令牌的环境变量名称
`lifecycle`	`"lazy"` / `"eager"` / `"keep-alive"`	连接策略（默认值： `lazy` ）
`idleTimeout`	数字	空闲断开连接前的分钟数
`debug`	布尔值	显示服务器标准错误输出

生命周期模式：

lazy（默认） — 首次调用工具时连接，空闲超时后断开
eager — 会话开始时连接，不会自动断开
keep-alive — 会话开始时连接，断开后自动重连

Step 4: Write the Config

步骤4：写入配置

Read the target config file if it exists
Merge the new server into the existing
```
mcpServers
```
object
Write the updated JSON

If the file doesn't exist, create it with the full structure:

json

{
  "mcpServers": {
    "server-name": { ... }
  }
}

Warn if a server with the same name already exists and confirm before overwriting.

读取目标配置文件（如果已存在）
将新服务器信息合并到现有的
```
mcpServers
```
对象中
写入更新后的JSON内容

如果文件不存在，则创建包含完整结构的文件：

json

{
  "mcpServers": {
    "server-name": { ... }
  }
}

如果同名服务器已存在，需发出警告并在覆盖前确认。

Step 5: Verify

步骤5：验证

Run
```
/reload
```
to pick up the new config
Use
```
mcp({ connect: "server-name" })
```
to test the connection
Use
```
mcp({ server: "server-name" })
```
to list available tools
Report success or troubleshoot connection errors

运行
```
/reload
```
以加载新配置
使用
```
mcp({ connect: "server-name" })
```
测试连接
使用
```
mcp({ server: "server-name" })
```
列出可用工具
报告连接成功或排查连接错误