> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 配置

> 如何添加、配置和管理 MCP 服务器

<div id="adding-mcp-servers">
  ## 添加 MCP 服务器
</div>

<div id="via-command-line">
  ### 通过命令行
</div>

添加 MCP 服务器的最快方法：

```bash theme={null}
# stdio 服务器 — 在 -- 后面传入命令
devin mcp add <name> -- <command> [args...]

# HTTP 服务器 — 将 URL 作为位置参数传入
devin mcp add <name> <URL>

# HTTP 服务器 — 或使用 --url 标志
devin mcp add <name> --url <URL>
```

传输类型会自动推断：URL 表示 HTTP (Streamable HTTP) ，末尾参数 (或 `--command`) 表示 stdio。

<Note>远程 MCP 服务器默认使用 Streamable HTTP。如果服务器返回 HTTP 4xx 错误，CLI 会回退到同一 URL 上的 SSE。如有需要，请显式设置 `"transport": "sse"`——请参阅下方的[旧版 SSE 回退](#legacy-sse-fallback)。</Note>

默认情况下，服务器会保存到 **local** 作用域 (`.devin/config.local.json`，已加入 gitignore) 。可使用 `-s`/\`--scope\`\` 更改：

```bash theme={null}
devin mcp add -s project <name> <URL>   # 通过 .devin/config.json 共享
devin mcp add -s user <name> <URL>      # 全局（~/.config/devin/config.json；Windows 上为 %APPDATA%\devin\config.json）
```

你也可以通过命令行管理服务器：

```bash theme={null}
devin mcp list              # List all configured servers
devin mcp get <name>        # Show details for a specific server
devin mcp remove <name>     # Remove a configured server
devin mcp login <name>      # Authenticate with a server via OAuth
devin mcp logout <name>     # Remove stored OAuth credentials
devin mcp enable <name>     # 启用已禁用的服务器
devin mcp disable <name>    # 禁用服务器而不将其移除
```

<div id="via-config-file">
  ### 通过配置文件
</div>

直接在配置文件的 `mcpServers` 部分添加服务器：

<Tabs>
  <Tab title="项目配置">
    ```json theme={null}
    // .devin/config.json
    {
      "mcpServers": {
        "server-name": {
          "command": "npx",
          "args": ["-y", "@company/mcp-server"],
          "env": {
            "API_KEY": "your-key"
          }
        }
      }
    }
    ```

    <Note>项目级服务器会通过版本控制与你的团队共享。</Note>
  </Tab>

  <Tab title="用户配置">
    ```json theme={null}
    // ~/.config/devin/config.json
    {
      "mcpServers": {
        "my-server": {
          "command": "node",
          "args": ["/path/to/my-server.js"],
          "env": {}
        }
      }
    }
    ```

    <Note>用户级服务器会应用于你的所有项目。</Note>
  </Tab>

  <Tab title="本地覆盖">
    ```json theme={null}
    // .devin/config.local.json
    {
      "mcpServers": {
        "server-name": {
          "command": "npx",
          "args": ["-y", "@company/mcp-server"],
          "env": {
            "API_KEY": "my-personal-key"
          }
        }
      }
    }
    ```

    <Note>本地配置会被 gitignore 忽略——可用于存放个人 API 密钥。</Note>
  </Tab>
</Tabs>

***

<div id="server-configuration-options">
  ## 服务器配置选项
</div>

MCP 服务器可配置为两种形式：**本地命令** (stdio 传输) 或**远程服务器** (HTTP 传输) 。

<div id="local-command-stdio">
  ### 本地命令 (stdio)
</div>

| 字段         | 类型        | 必填 | 描述                                                                 |
| ---------- | --------- | -- | ------------------------------------------------------------------ |
| `command`  | string    | 是  | 要运行的可执行文件                                                          |
| `args`     | string\[] | 否  | 命令行参数                                                              |
| `env`      | object    | 否  | 要设置的环境变量                                                           |
| `disabled` | boolean   | 否  | 设为 `true` 可跳过此服务器 (请参阅[启用和禁用服务器](#enabling-and-disabling-servers)) |

<div id="remote-server-streamable-http">
  ### 远程服务器 (Streamable HTTP)
</div>

| 字段                  | 类型      | 必填 | 描述                                                                                                                                                                                                                                                                                |
| ------------------- | ------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`               | string  | 是  | MCP 服务器端点的 URL                                                                                                                                                                                                                                                                    |
| `transport`         | string  | 否  | `"http"` (Streamable HTTP，URL 型服务器的默认值) 或 `"sse"` (旧版 SSE) 。设置为 `"http"` 或省略时，CLI 会先尝试 Streamable HTTP，并在出现 4xx 错误时回退到 SSE ([依据规范](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility)) 。如果服务器的 SSE 端点位于其他路径，请显式设置为 `"sse"`。 |
| `headers`           | object  | 否  | 请求中附带的自定义 HTTP 标头                                                                                                                                                                                                                                                                 |
| `oauthClientId`     | string  | 否  | 预先注册的 OAuth 客户端 ID，适用于不支持动态客户端注册 (DCR) 的服务器，例如 GitHub。请参阅下方的“预先注册的 OAuth 客户端”部分。                                                                                                                                                                                                  |
| `oauthClientSecret` | string  | 否  | OAuth 客户端密钥，适用于机密客户端。请与 `oauthClientId` 搭配使用。                                                                                                                                                                                                                                     |
| `disabled`          | boolean | 否  | 设置为 `true` 可跳过此服务器 (参见[启用和禁用服务器](#enabling-and-disabling-servers))                                                                                                                                                                                                                |

<div id="examples">
  ### 示例
</div>

<AccordionGroup>
  <Accordion title="GitHub（stdio）">
    ```json theme={null}
    {
      "mcpServers": {
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": {
            "GITHUB_TOKEN": "ghp_..."
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Notion（HTTP + OAuth）">
    ```json theme={null}
    {
      "mcpServers": {
        "notion": {
          "url": "https://mcp.notion.com/mcp",
          "transport": "http"
        }
      }
    }
    ```

    <Note>添加基于 OAuth 的服务器后，运行 `devin mcp login notion` 完成身份验证。请参阅下方的[身份验证](#authentication)。</Note>
  </Accordion>

  <Accordion title="Linear（HTTP + OAuth）">
    ```json theme={null}
    {
      "mcpServers": {
        "linear": {
          "url": "https://mcp.linear.app/mcp",
          "transport": "http"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Atlassian / Jira（HTTP + OAuth）">
    ```json theme={null}
    {
      "mcpServers": {
        "atlassian": {
          "url": "https://mcp.atlassian.com/v1/mcp",
          "transport": "http"
        }
      }
    }
    ```

    <Note>添加后，运行 `devin mcp login atlassian` 完成身份验证。每个 MCP 客户端 (Windsurf、Claude Code、Devin CLI) 都会维护各自的 OAuth 会话，因此即使你已在其他工具中完成身份验证，也仍需单独登录。</Note>
  </Accordion>

  <Accordion title="自定义服务器（stdio）">
    ```json theme={null}
    {
      "mcpServers": {
        "my-tools": {
          "command": "python",
          "args": ["./scripts/mcp-server.py"],
          "env": {
            "DB_URL": "postgres://localhost/mydb"
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

<div id="authentication">
  ## 身份验证
</div>

某些远程 MCP 服务器需要进行 OAuth 身份验证。将基于 OAuth 的服务器添加到你的配置中后，使用 `login` 命令进行身份验证：

```bash theme={null}
devin mcp login <server-name>
```

例如：

```bash theme={null}
devin mcp login notion    # 使用 Notion 进行身份验证
devin mcp login linear    # 使用 Linear 进行身份验证
```

这会打开一个浏览器窗口，你可以在其中授权访问。OAuth 令牌会存储在本地，并自动自动刷新。

你也可以按需请求特定的 OAuth 作用域：

```bash theme={null}
devin mcp login notion --scopes read,write
```

要删除某个服务器已存储的 OAuth 凭据：

```bash theme={null}
devin mcp logout <server-name>
```

<Note>
  如果服务器支持 OAuth，首次使用该服务器时，系统也会提示你自动完成身份验证。
</Note>

<div id="pre-registered-oauth-clients">
  ### 预先注册的 OAuth 客户端
</div>

大多数基于 OAuth 的 MCP 服务器都支持[动态客户端注册](https://datatracker.ietf.org/doc/html/rfc7591) (DCR) ，因此 Devin CLI 会自动注册，无需你提供任何客户端凭据。

有些提供商 (例如 GitHub) 不支持 DCR，而是要求使用**预先注册的** OAuth 客户端。对于这类提供商，请通过 `oauthClientId` / `oauthClientSecret` 提供客户端 ID；如果是机密客户端，还需提供客户端密钥：

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "transport": "http",
      "oauthClientId": "Iv1.abc123def456",
      "oauthClientSecret": "${env:MY_MCP_CLIENT_SECRET}"
    }
  }
}
```

设置 `oauthClientId` 后，Devin CLI 会跳过动态客户端注册，并在 OAuth 流程中使用你预先注册的客户端。像平常一样，运行 `devin mcp login <name>` (或在首次使用时触发) 即可完成身份验证。

你也可以在添加服务器或登录服务器时，通过命令行设置这些项：

```bash theme={null}
devin mcp add my-server <URL> --oauth-client-id <ID> --oauth-client-secret <SECRET>
devin mcp login my-server --oauth-client-id <ID> --oauth-client-secret <SECRET>
```

<Note>
  `oauthClientId` / `oauthClientSecret` 是在授权流程中使用的 OAuth 客户端凭据。它们**不是**通用的、按请求提供的凭据——如果服务器需要静态令牌，请改用 `headers` (HTTP) 或 `env` (stdio) 。
</Note>

<Warning>
  不要将客户端密钥提交到共享配置中。请通过环境变量 (`${env:VAR}`) 引用它，从文件中读取它 (`${file:/path}`) ，或将其放入 `.devin/config.local.json` (已加入 git 忽略) 。请参阅下方的“管理 secrets”部分。
</Warning>

***

<div id="enabling-and-disabling-servers">
  ## 启用和禁用服务器
</div>

你可以在不删除其配置的情况下临时禁用 MCP 服务器。已禁用的服务器会在工具自动发现时被跳过——其工具不会显示，服务器进程也不会启动。

```bash theme={null}
devin mcp disable <name>    # 禁用服务器
devin mcp enable <name>     # 重新启用
```

这会在配置文件的 server 条目中将 `"disabled": true` 标记设为启用。使用 `-s`/`--scope` 可指定特定作用域：

```bash theme={null}
devin mcp disable -s project my-server
devin mcp enable -s user my-server
```

你也可以直接在配置文件中设置此标志：

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@company/mcp-server"],
      "disabled": true
    }
  }
}
```

<Note>如果你想保留服务器的配置 (包括环境变量和 OAuth 凭据) ，但暂时停用它，禁用功能就很有用——例如，可以缩短启动时间或隔离问题。</Note>

***

<div id="managing-secrets">
  ## 管理敏感凭据
</div>

<Warning>
  切勿将 API key 或其他敏感凭据提交到版本控制中。请使用 `.devin/config.local.json` 存放敏感值。
</Warning>

对于团队项目，推荐采用以下方式：

1. 在 `.devin/config.json` 中定义服务器，并使用占位符或不设置 env vars
2. 每位团队成员在 `.devin/config.local.json` 中添加自己的个人密钥

本地配置文件会自动被 git 排除。

***

<div id="mcp-permissions">
  ## MCP 权限
</div>

你可以在权限配置中，将特定的 MCP 工具设为预先批准、拒绝或始终询问：

```json theme={null}
{
  "permissions": {
    "allow": [
      "mcp__github__list_issues",
      "mcp__github__create_issue"
    ],
    "deny": [
      "mcp__github__delete_repo"
    ],
    "ask": [
      "mcp__linear__*"
    ]
  }
}
```

**权限匹配模式：**

| 模式                  | 匹配对象             |
| ------------------- | ---------------- |
| `mcp__server__tool` | 特定服务器上的特定工具      |
| `mcp__server__*`    | 特定服务器上的所有工具      |
| `mcp__*`            | 所有服务器上的所有 MCP 工具 |

***

<div id="organization-restrictions">
  ## 组织限制
</div>

如果你所在的是 Enterprise 团队，Admin 可能会限制你可连接的 MCP 服务器。如果团队已禁用 MCP，或者你已配置的某个服务器不在团队的 allowlist 中，或不在强制使用的 **MCP 注册表** 中，该服务器就可能被阻止——这样一来，它将无法连接，其工具也无法使用。详见[团队设置 — MCP 注册表](/zh/cli/enterprise/team-settings#mcp-registry)。

***

<div id="troubleshooting">
  ## 故障排查
</div>

<AccordionGroup>
  <Accordion title="远程服务器要求身份验证 / OAuth 错误">
    如果你在连接远程 MCP 服务器时看到 `Auth required` 或 `AuthRequired` 之类的错误，说明该服务器需要 OAuth 身份验证。

    运行：

    ```bash theme={null}
    devin mcp login <server-name>
    ```

    每个 MCP 客户端都需要单独进行身份验证。即使你已经在 Windsurf 或 Claude Code 中完成了身份验证，仍需单独为 Devin CLI 运行 `devin mcp login`。

    要确认你的身份验证状态，可以尝试先移除凭据再重新添加：

    ```bash theme={null}
    devin mcp logout <server-name>
    devin mcp login <server-name>
    ```
  </Accordion>

  <Accordion title="服务器无法启动">
    确认该命令在 Devin CLI 外部也能正常运行：

    ```bash theme={null}
    npx -y @modelcontextprotocol/server-github
    ```

    检查是否已设置所有必需的环境变量。
  </Accordion>

  <Accordion title="工具未显示">
    让 Agent 列出 MCP 服务器和工具。服务器可能需要一点时间完成初始化。
  </Accordion>

  <Accordion title="权限被拒绝">
    检查你的权限配置。MCP 工具默认会提示你批准。将它们添加到 `permissions.allow` 中即可自动批准。
  </Accordion>

  <Accordion title="旧版 SSE 回退">
    连接到 HTTP 服务器时，Devin CLI 会先尝试 **Streamable HTTP**。如果服务器返回 HTTP 4xx 错误 (如 404 或 405) ，它会自动回退到**同一已配置 URL**上的**旧版 SSE**。这遵循了 [MCP 规范中的向后兼容性指南](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/transports/#backwards-compatibility)。

    只有在收到 4xx 响应时才会触发回退——连接错误、超时和 5xx 响应会直接报错，不会尝试 SSE。

    如果你服务器的 SSE 端点位于其他路径 (如 `/sse` 而不是 `/mcp`) ，请将 `"transport": "sse"` 设置为使用该 SSE URL，以便直接连接，而不先尝试 Streamable HTTP。

    如果两种传输方式都失败，错误消息会包含两次尝试的详细信息，帮助你排查问题。
  </Accordion>
</AccordionGroup>