MCP 服务器

本指南介绍如何为 Sink 中的 Agent 配置 MCP Server，使其能够访问外部工具和数据源。

什么是 MCP Server？

MCP（Model Context Protocol）Server 是 Agent 用来访问外部工具和数据源的一种标准方式。例如，MCP Server 可以提供：

• 文件系统访问
• 数据库查询
• Web API 调用
• 代码分析工具
• 等等

Sink 支持两种类型的 MCP Server：

• stdio：在本地运行的可执行程序
• http：远程 HTTP 服务

MCP 配置文件

MCP Server 通过 mcp.json 配置文件定义。该文件应位于以下位置之一：

• Workspace 级：<workspace>/.sink/mcp.json
• User 级：~/.sink/mcp.json
• Builtin 级（发行版预置）

Workspace 级配置会覆盖 User 级，User 级会覆盖 Builtin 级。

基本格式

mcp.json 的基本结构：

{
  "mcpServers": {
    "server-id": {
      "type": "stdio",
      "command": "executable-path",
      "args": ["--arg1", "--arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

配置 Stdio 类型 Server

Stdio 类型 Server 是在本地运行的可执行程序。Agent 通过标准输入/输出与其通信。

基本示例

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "mcp-server-filesystem",
      "args": ["--root", "/home/user"],
      "env": {
        "DEBUG": "false"
      }
    }
  }
}

字段说明

使用 npx 运行

可以通过 npx 直接运行 npm 包：

{
  "mcpServers": {
    "web-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-web-search"]
    }
  }
}

环境变量

如果 MCP Server 需要特殊的环境变量（如 API key），可以在 env 中指定：

{
  "mcpServers": {
    "openai": {
      "type": "stdio",
      "command": "mcp-server-openai",
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

注意：不要在 mcp.json 中直接存储敏感的 API key。改为在 settings.json 中设置环境变量，然后在 mcp.json 中引用。例如：

settings.json:

{
  "env": {
    "OPENAI_API_KEY": "sk-..."
  }
}

mcp.json:

{
  "mcpServers": {
    "openai": {
      "type": "stdio",
      "command": "mcp-server-openai",
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

配置 HTTP 类型 Server

HTTP 类型 Server 是通过网络访问的远程服务。

基本示例

{
  "mcpServers": {
    "api-service": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token-here"
      }
    }
  }
}

字段说明

禁用 Server

可以在不删除配置的情况下临时禁用 MCP Server，使用 metadata.disabled 字段：

{
  "mcpServers": {
    "disabled-server": {
      "type": "stdio",
      "command": "some-command",
      "metadata": {
        "disabled": true
      }
    }
  }
}

也可以使用环境变量动态控制：

{
  "mcpServers": {
    "optional-server": {
      "type": "stdio",
      "command": "some-command",
      "metadata": {
        "disabled": "${DISABLE_SERVER}"
      }
    }
  }
}

然后在 settings.json 中设置：

{
  "env": {
    "DISABLE_SERVER": "false"
  }
}

内置 MCP Server

Sink 自动为每个任务注册一个内置的 sink MCP Server，提供以下工具：

任务管理工具

• task_complete — 标记任务完成
• task_spawn — 创建子任务。参数：prompt（描述）、profileId（Profile 选择）、executionMode（individual 或 team）、awaitCompletion（等待子任务完成后返回）、managed（托管标志）、configOverrides（覆盖配置默认值）、questionnaireAnswers（回答 Profile 问卷问题）
• task_info — 查询任务信息
• task_send_message — 向其他任务发送消息。支持两种类型：task_message（纯文本消息）和 task_reopen_request（要求目标任务在完成后重新打开自身）。使用 task_info 并指定 taskId: "parent" 可发现父任务的 ID
• task_reopen — 重新打开已完成的任务

配置查询工具

• profile_list — 列出所有 Profile
• profile_get — 获取特定 Profile 详情
• runtime_list — 列出所有 Runtime
• runtime_get — 获取特定 Runtime 详情
• skill_list — 列出所有 Skill
• skill_get — 获取特定 Skill 详情
• mcp_list — 列出所有 MCP Server
• mcp_get — 获取特定 MCP Server 详情

Cron 定时任务工具

Agent 可以通过以下工具管理定时任务：

• cron_set — 为当前任务设置定时通知（Cron 触发时向任务发送消息）
• cron_spawn — 设置定时自动创建子任务（Cron 触发时用指定 Profile 创建新任务）。注意：需要 task_spawn 工具已启用；如果 task_spawn 被禁用，cron_spawn 也会自动不可用。
• cron_remove — 删除指定的定时任务
• cron_list — 列出当前任务的所有定时任务

内置 sink MCP Server 无需在 mcp.json 中配置，所有任务都能自动访问它。

常见 MCP Server

以下是一些常用的开源 MCP Server：

文件系统访问

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

Web 浏览

{
  "mcpServers": {
    "puppeteer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Git 仓库

{
  "mcpServers": {
    "git": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    }
  }
}

故障排除

MCP Server 无法启动

症状：任务启动时 MCP Server 连接失败

检查项：

1. 确认可执行文件存在且有执行权限：

   which command-name
   ls -l /path/to/command
   

2. 尝试手动运行 server 检查是否有错误：

   /path/to/mcp-server
   

3. 检查日志获取更多信息（如果配置了调试模式）

环境变量未生效

症状：${VAR} 在 mcp.json 中未被替换

原因：变量未在 settings.json 中定义，或 shell 环境中不存在

解决方案：

1. 确认在 settings.json 中定义了该变量：

   {
     "env": {
       "VAR": "value"
     }
   }
   

2. 或者确认环境变量在 shell 中已设置：

   export VAR="value"
   sink gateway
   

HTTP Server 连接失败

症状：HTTP 类型 server 连接超时或被拒绝

检查项：

1. 确认 URL 正确且服务在线：

   curl -H "Authorization: Bearer token" https://api.example.com/mcp
   

2. 检查防火墙是否阻止连接
3. 验证认证令牌是否有效

后续步骤

1. 管理 Profile — 为不同 Agent 分配不同的 MCP Server
2. 配置 Runtime — 了解如何配置 Agent 运行时
3. 快速开始教程 — 创建并运行你的第一个任务