MCP(Model Context Protocol)
MCP 让 KOPI AI AGENT 能够连接外部工具服务器,从而使 agent 可以使用位于 Kopi Agent 本身之外的工具 —— GitHub、数据库、文件系统、浏览器工具栈、内部 API 等等。
如果你一直希望 Kopi Agent 能使用某个已在别处存在的工具,MCP 通常是最简洁的实现方式。
MCP 提供的能力
- 无需先编写 Kopi Agent 原生工具,即可访问外部工具生态
- 在同一份 config 中同时支持本地 stdio 服务器和远程 HTTP MCP 服务器
- 启动时自动发现并注册工具
- 在服务器支持时,为 MCP resources 和 prompts 提供实用封装
- 按服务器进行过滤,只暴露你确实希望 Kopi Agent 看到的 MCP 工具
快速开始
-
标准安装已内置 MCP 支持 —— 无需额外步骤。
-
将一个 MCP 服务器添加到
~/.kopi/config.yaml:
mcp_servers:
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
- 启动 Kopi Agent:
kopi chat
- 让 Kopi Agent 使用由 MCP 提供的能力。
例如:
List the files in /home/user/projects and summarize the repo structure.
Kopi Agent 会发现该 MCP 服务器的工具,并像使用其他工具一样使用它们。
目录:Nous 审核通过的 MCP 一键安装
Kopi Agent 附带一份精选的 MCP 服务器目录,这些服务器均经过 Nous 员工审核 并合入。它们默认处于禁用状态 —— 只安装你确实需要的。
kopi mcp # interactive picker (default)
kopi mcp catalog # plain-text list, scriptable
kopi mcp install n8n # install a catalog entry by name
选择器会显示每个条目及其当前状态:
n8n available Manage and inspect n8n workflows from Kopi Agent
linear enabled Linear issue/project management (remote OAuth)
github installed (disabled) GitHub repo + PR tools
在某一行上按 Enter 即可安装(并完成所需的凭据配置)、
启用、禁用或卸载。目录条目存储在 kopi-ai-agent 仓库的
optional-mcps/ 下 —— 位于该目录中即代表
已获 Nous 批准。没有社区提交层级;条目通过
合并 PR 的方式添加。
目录条目可能需要:
- API key —— Kopi Agent 会在安装时提示输入,并将该值写入
~/.kopi/.env。非机密值(如 base URL)会写入同一文件。 - OAuth(远程 MCP)—— 以
auth: oauth的形式写入你的 config;MCP client 会在首次连接时打开浏览器。 - OAuth(第三方 provider,如 Google/GitHub)—— 如果你尚未完成身份验证,
Kopi Agent 会引导你前往
kopi auth <provider>。
安装时的工具选择
配置好凭据后,Kopi Agent 会探测该 MCP 服务器以列出它暴露的每一个 工具,并展示一份勾选清单:
Select tools for 'linear' (SPACE toggle, ENTER confirm)
[x] find_issues Find issues matching a query
[x] get_issue Get a single issue
[x] create_issue Create a new issue
[ ] delete_workspace Delete a Linear workspace
...
预先勾选的行来自:
- 你之前的选择,如果你此前安装过该条目(重新安装 会保留你原有的设置 —— manifest 中的默认值不会覆盖它)
- manifest 的
tools.default_enabled,如果该条目声明了它(部分 目录条目会预先剔除具有副作用或很少用到的工具) - 全部工具,如果以上都不适用
按 ENTER 提交勾选清单。只有勾选的工具会被写入
mcp_servers.<name>.tools.include。如果你全选,则不会写入任何过滤器
(config 结构最简洁,行为完全一致)。
如果探测失败(服务器不可达、OAuth 尚未完成、
后端服务未运行),安装仍会成功:会直接应用 manifest 的
tools.default_enabled(如果已声明),或者不写入
过滤器(如果未声明)。待服务器
可达后重新运行 kopi mcp configure <name> 即可细化选择。
信任模型
安装目录条目会执行 manifest 中指定的一切内容 —— git clone、
该条目的 bootstrap 命令(pip install、npm install 等),以及
最终 MCP 服务器自身的代码。manifest 需经过向
kopi-ai-agent 仓库提交 PR 的评审把关,因此每个条目在发布前都已由 Nous 审核 ——
但你仍应在安装前阅读 manifest,尤其是
source: 字段中的仓库、install.bootstrap: 命令,以及任何
transport.command: 调用。
Manifest 位于 GitHub 上的
optional-mcps/<name>/manifest.yaml。
选择器还会在安装时打印该 manifest 的 source: URL,
以便你快速验证上游仓库。Web 控制台的 MCP
页面会针对每个目录条目展示同样的细节 —— transport、认证类型、
endpoint URL(HTTP)或命令 + 参数(stdio)、git 安装来源/ref 以及
引导命令和设置说明 —— 并将 source: 渲染为
可点击链接,这样你可以在点击 Install 之前准确了解某个条目会连接什么或
运行什么。
Manifest 版本兼容性
Manifest 会固定一个 manifest_version。目录具有向前兼容性:如果某个
PR 添加了一个 manifest_version 比你已安装的 Kopi Agent 所理解的版本更新的条目,
选择器会显示警告(⚠ '<name>' requires a newer Kopi Agent) for that entry instead of silently hiding it. Run kopi update
看到此提示时,请安装最新版本的 Kopi Agent。
运行时 ${ENV_VAR} 替换
在条目的 transport.command、transport.args、transport.url
和 headers 中,${VAR} 占位符会在服务器连接时
从环境变量(包含 ~/.kopi/.env 中的所有内容)解析。
当目录条目需要引用用户在其他地方配置的值时,这很有用
—— 例如 ${HOME}/foo 或 ${MY_PROVIDER_TOKEN}。
请注意,这与目录 manifest 中的 ${INSTALL_DIR} 不同,后者
会在安装时替换为目录克隆该条目
仓库所在的路径。
后续更新工具选择
kopi mcp configure linear
会重新打开同一份勾选清单,并预先勾选你当前的选择。当你想启用更多工具, 或者服务器新增了你希望启用的工具时,可以使用此功能。
更新目录 manifest
MCP 永远不会自动更新。如果 manifest 版本发生变化,请在 Kopi Agent 更新后
重新运行 kopi mcp install <name> 进行刷新。
要将某个 MCP 添加到目录中,请向
optional-mcps/
提交一个 PR。
两种 MCP 服务器
Stdio 服务器
Stdio 服务器作为本地子进程运行,通过 stdin/stdout 进行通信。
mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
在以下情况使用 stdio 服务器:
- 服务器已安装在本地
- 你希望低延迟地访问本地资源
- 你参考的 MCP 服务器文档中展示了
command、args和env
HTTP 服务器
HTTP MCP 服务器是 Kopi Agent 直接连接的远程端点。
mcp_servers:
remote_api:
url: "https://mcp.example.com/mcp"
headers:
Authorization: "Bearer ***"
在以下情况使用 HTTP 服务器:
- MCP 服务器托管在其他地方
- 你的组织暴露了内部 MCP 端点
- 你不希望 Kopi Agent 为该集成启动本地子进程
OAuth 认证的 HTTP 服务器
大多数托管的 MCP 服务器(Linear、Sentry、Atlassian、Asana、Figma、Stripe 等)要求使用 OAuth 2.1 而非静态 bearer token。设置 auth: oauth 后,Kopi Agent 会通过 MCP Python SDK 处理服务发现、动态客户端注册、PKCE、token 交换、刷新以及升级认证(step-up auth)。
mcp_servers:
linear:
url: "https://mcp.linear.app/mcp"
auth: oauth
首次连接时,Kopi Agent 会打印一个授权 URL,在可能的情况下打开你的浏览器,并在本地回环端口上等待 OAuth 回调。token 会以 0o600 权限缓存在 ~/.kopi/mcp-tokens/<server>.json;之后的运行会静默复用这些 token,直到刷新失败。
远程 / 无头主机。 当 Kopi Agent 运行在与你的浏览器不同的机器上时,回环回调无法到达你的笔记本电脑。有两种方式可以完成该流程:
- 粘贴回传(无需配置): 在交互式终端中,Kopi Agent 会在授权 URL 旁边打印 "Or paste the redirect URL here…"。在浏览器中打开该 URL,完成授权,然后复制浏览器最终所在的完整 URL(该重定向会显示连接错误——这是正常的),将其粘贴到提示符处。裸
?code=…&state=…query string 也可以使用。 - SSH 端口转发: 在单独的终端中执行
ssh -N -L <port>:127.0.0.1:<port> user@host,然后让重定向流程正常进行。
参见 OAuth over SSH / Remote Hosts 获取完整操作指南,包括不支持 DCR 的服务器(例如 Slack)、预注册的 client_id/client_secret、scope 自定义,以及通过 kopi mcp login <server> 重新认证。
陷阱——不支持自动注册的 provider(Google Drive、Atlassian)。 有些服务器会拒绝裸 auth: oauth 所依赖的动态客户端注册步骤(RFC 7591)——Google 官方的 Drive 服务器(https://drivemcp.googleapis.com/mcp/v1)会返回 400 Bad Request,因此不会创建 OAuth client,也不会获取 token。其症状很隐晦:这些服务器也会在不认证的情况下提供 tools/list,所以 kopi mcp login 可以列出工具并看起来一切正常,但之后每次真正的工具调用都会超时。kopi mcp login 现在能检测到这种情况(它会检查是否确实有 token 落盘),并提示你提供自己的 OAuth client。在 provider 的控制台中创建一个,然后添加到配置中:
mcp_servers:
googledrive:
url: "https://drivemcp.googleapis.com/mcp/v1"
auth: oauth
oauth:
client_id: "<your-oauth-client-id>"
client_secret: "<your-oauth-client-secret>"
然后运行 kopi mcp login googledrive——有了预注册的 client,Kopi Agent 会跳过注册,执行正常的浏览器授权流程。
陷阱——配置自动重载的竞争条件。 当你从正在运行的 Kopi Agent 会话内部编辑 ~/.kopi/config.yaml 时,CLI 会自动重载 MCP 连接,超时时间为 30 秒。这对于交互式 OAuth 流程来说不够。先添加条目,然后从一个全新的终端运行 kopi mcp login <server>——它会等待完整的 5 分钟,让你完成认证。
mTLS / 客户端证书
需要双向 TLS(客户端证书认证)的远程 HTTP MCP 服务器可通过 client_cert / client_key 支持。Kopi Agent 会将解析后的证书传递给底层 HTTP 客户端以完成 TLS 握手。
client_cert 接受三种形式:
- 单个合并的 PEM 路径——一个同时包含证书和私钥的文件:
mcp_servers:
internal_api:
url: "https://mcp.internal.example.com/mcp"
client_cert: "~/.certs/mcp-client.pem"
- 一个
[cert, key]2 元组——证书和密钥分别放在不同文件中(等同于设置client_cert+client_key):
mcp_servers:
internal_api:
url: "https://mcp.internal.example.com/mcp"
client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key"]
- 一个
[cert, key, password]3 元组——当私钥被加密时,第三个元素是密钥口令:
mcp_servers:
internal_api:
url: "https://mcp.internal.example.com/mcp"
client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key", "${MCP_KEY_PASSWORD}"]
你也可以通过 client_cert(合并的 PEM)加一个显式的 client_key 将证书和密钥完全分开。路径支持 ~ 展开;文件缺失时会抛出清晰的、限定到具体服务器的错误,而不是晦涩的 TLS 握手失败。
基本配置参考
Kopi Agent 从 mcp_servers 下的 ~/.kopi/config.yaml 读取 MCP 配置。
常用键
| 键 | 类型 | 含义 |
|---|---|---|
command | string | stdio MCP server 的可执行文件 |
args | list | stdio server 的启动参数 |
env | mapping | 传递给 stdio server 的环境变量 |
url | string | HTTP MCP endpoint |
headers | mapping | 远程 server 的 HTTP 头 |
client_cert | string | list | mTLS 的客户端证书 —— 合并 PEM 路径,或 [cert, key] / [cert, key, password] |
client_key | string | 客户端私钥 PEM 路径(当与 client_cert 分离时) |
timeout | number | 工具调用超时时间 |
connect_timeout | number | 初始连接超时时间(同时约束 MCP initialize 握手) |
idle_timeout_seconds | number | 在此秒数内没有工具调用后回收该 stdio server(0 = 永不,默认)。下次工具调用时该 server 会透明重启。 |
max_lifetime_seconds | number | 在达到此总运行时长后回收该 stdio server(0 = 永不,默认)。下次使用时透明重启。 |
enabled | bool | 若为 false,Kopi Agent 会完全跳过该 server |
supports_parallel_tool_calls | bool | 若为 true,来自该 server 的工具可以并发运行 |
tools | mapping | 按 server 进行的工具过滤与实用工具策略 |
最小 stdio 示例
mcp_servers:
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
回收占用大量内存的 stdio server
基于浏览器的 MCP server(例如 @playwright/mcp)在首次工具调用后会
常驻一整个 Chromium 实例——数百 MB 内存永远不会被
释放。启用自动回收后,server 会在达到空闲/存活时间上限后被销毁,
随后在其某个工具下一次被调用时透明重启(其工具全程保持
已注册状态):
mcp_servers:
playwright:
command: "npx"
args: ["-y", "@playwright/mcp@latest", "--headless"]
idle_timeout_seconds: 900 # recycle after 15 min without a tool call
max_lifetime_seconds: 86400 # and at least once a day regardless
最小 HTTP 示例
mcp_servers:
company_api:
url: "https://mcp.internal.example.com"
headers:
Authorization: "Bearer ***"
内置预设
对于常见的 MCP server,kopi mcp add 接受一个 --preset 标志,会自动填入传输相关细节,你无需再去查找 command 和 args。预设只提供默认值——你在同一条命令行上传入的其他内容(环境变量、请求头、过滤)仍然优先。
| 预设 | 配置内容 |
|---|---|
codex | Codex CLI 的 MCP server(通过 stdio 的 codex mcp-server)。要求 PATH 中存在 codex CLI。 |
# Add Codex CLI as an MCP server in one line
kopi mcp add codex --preset codex
该命令写入等价于以下内容的配置:
mcp_servers:
codex:
command: "codex"
args: ["mcp-server"]
你可以使用任意本地名称(kopi mcp add my-codex --preset codex 即可);预设仅提供 command/args 的默认值。
Kopi Agent 如何注册 MCP 工具
Kopi Agent 会给 MCP 工具加上前缀,以避免与内置名称冲突:
mcp_<server_name>_<tool_name>
示例:
| Server | MCP 工具 | 注册名称 |
|---|---|---|
filesystem | read_file | mcp_filesystem_read_file |
github | create-issue | mcp_github_create_issue |
my-api | query.data | mcp_my_api_query_data |
实际上,通常不需要手动调用带前缀的名称——Kopi Agent 会看到该工具并在常规推理过程中选择它。
MCP 实用工具
在受支持时,Kopi Agent 还会围绕 MCP resources 和 prompts 注册实用工具:
list_resourcesread_resourcelist_promptsget_prompt
这些工具按 server 注册,并使用相同的前缀模式,例如:
mcp_github_list_resourcesmcp_github_get_prompt
重要提示
这些实用工具现在具备能力感知(capability-aware)特性:
- 只有当 MCP 会话确实支持 resource 操作时,Kopi Agent 才会注册 resource 相关的实用工具
- 只有当 MCP 会话确实支持 prompt 操作时,Kopi Agent 才会注册 prompt 相关的实用工具
因此,只暴露可调用工具而不提供 resources/prompts 的 server 不会得到这些额外的包装工具。
按 server 过滤
你可以控制每个 MCP server 向 Kopi Agent 提供哪些工具,从而精细管理你的工具命名空间。
完全禁用某个 server
mcp_servers:
legacy:
url: "https://mcp.legacy.internal"
enabled: false
若为 enabled: false,Kopi Agent 会完全跳过该 server,甚至不会尝试建立连接。
白名单过滤 server 工具
mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
tools:
include: [create_issue, list_issues]
仅注册这些 MCP server 工具。
黑名单过滤 server 工具
mcp_servers:
stripe:
url: "https://mcp.stripe.com"
tools:
exclude: [delete_customer]
除被排除的工具外,其余 server 工具都会被注册。
优先级规则
如果两者同时存在:
tools:
include: [create_issue]
exclude: [create_issue, delete_issue]
include 优先。
同时过滤实用工具
你也可以单独禁用 Kopi Agent 添加的实用包装工具:
mcp_servers:
docs:
url: "https://mcp.docs.example.com"
tools:
prompts: false
resources: false
这意味着:
tools.resources: false会禁用list_resources和read_resourcetools.prompts: false会禁用list_prompts和get_prompt
完整示例
mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
tools:
include: [create_issue, list_issues, search_code]
prompts: false
stripe:
url: "https://mcp.stripe.com"
headers:
Authorization: "Bearer ***"
tools:
exclude: [delete_customer]
resources: false
legacy:
url: "https://mcp.legacy.internal"
enabled: false
如果所有内容都被过滤掉会怎样?
如果你的配置过滤掉了所有可调用工具,并禁用或省略了所有受支持的实用工具,Kopi Agent 不会为该 server 创建空的运行时 MCP 工具集。
这样可以保持工具列表的整洁。
运行时行为
发现时机
Kopi Agent 在启动时发现 MCP 服务器,并将其工具注册到常规工具注册表中。
动态工具发现
MCP 服务器可以在运行时通过发送 notifications/tools/list_changed 通知来告知 Kopi Agent 其可用工具发生了变化。当 Kopi Agent 收到该通知时,它会自动重新获取该服务器的工具列表并更新注册表 —— 无需手动 /reload-mcp。
这对于能力会动态变化的 MCP 服务器非常有用(例如:当加载新的数据库架构时添加工具的服务器,或当服务下线时移除工具的服务器)。
刷新操作受锁保护,因此来自同一服务器的快速连续通知不会导致刷新操作相互重叠。提示词和资源变更通知(prompts/list_changed、resources/list_changed)会被接收,但目前不会据此执行操作。
重新加载
如果你更改了 MCP config,请使用:
/reload-mcp
这会从 config 中重新加载 MCP 服务器,并刷新可用工具列表。对于由服务器自身推送的运行时工具变更,请参阅上文的动态工具发现。
Toolsets
每个配置的 MCP 服务器在至少贡献一个已注册工具时,还会创建一个运行时 toolset:
mcp-<server>
这使得在 toolset 层面理解和管理 MCP 服务器变得更加容易。
安全模型
Stdio 环境变量过滤
对于 stdio 服务器,Kopi Agent 不会盲目传递你的完整 shell 环境变量。
只有显式配置的 env 加上安全的基线环境变量会被传递。这可以减少意外的敏感信息泄露。
Config 级别的暴露控制
新增的过滤功能同时也是一种安全控制手段:
- 禁用你不希望模型看到的危险工具
- 为敏感服务器仅暴露最小的白名单
- 当你不想暴露该能力面时,禁用 resource/prompt 包装器
示例用例
具有最小化 issue 管理能力面的 GitHub 服务器
mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
tools:
include: [list_issues, create_issue, update_issue]
prompts: false
resources: false
使用方式如下:
Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.
移除了危险操作的 Stripe 服务器
mcp_servers:
stripe:
url: "https://mcp.stripe.com"
headers:
Authorization: "Bearer ***"
tools:
exclude: [delete_customer, refund_payment]
使用方式如下:
Look up the last 10 failed payments and summarize common failure reasons.
针对单个项目根目录的 Filesystem 服务器
mcp_servers:
project_fs:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]
使用方式如下:
Inspect the project root and explain the directory layout.
故障排查
MCP 服务器无法连接
请检查:
# Verify MCP deps are installed (already included in standard install)
cd ~/.kopi/kopi-ai-agent && uv pip install -e ".[mcp]"
node --version
npx --version
然后验证你的 config 并重启 Kopi Agent。
工具未出现
可能的原因:
- 服务器连接失败
- 发现过程失败
- 你的过滤配置排除了这些工具
- 该服务器上不存在对应的 utility 能力
- 服务器通过
enabled: false被禁用
如果你是有意进行过滤,那么这是预期行为。
为什么 resource 或 prompt utility 没有出现?
因为 Kopi Agent 现在仅在以下两个条件同时满足时才注册这些包装器:
- 你的 config 允许它们
- 服务器会话实际支持该能力
这是有意为之的设计,可以保持工具列表的真实性和可靠性。
并行工具调用
默认情况下,MCP 工具会顺序执行 —— 一次执行一个。如果你的 MCP 服务器暴露的工具可以安全地并发运行(例如只读查询、相互独立的 API 调用),你可以选择启用并行执行:
mcp_servers:
docs:
command: "docs-server"
supports_parallel_tool_calls: true
当 supports_parallel_tool_calls 为 true 时,Kopi Agent 可能会在单个工具调用批次中同时执行来自该服务器的多个工具,就像它对内置只读工具(web_search、read_file 等)所做的那样。
仅对那些工具可安全同时运行的 MCP 服务器启用并行调用。如果工具会读写共享状态、文件、数据库或外部资源,请在启用此设置前仔细评估读写竞争条件。
MCP Sampling 支持
MCP 服务器可以通过 sampling/createMessage 协议向 Kopi Agent 请求 LLM 推理。这允许 MCP 服务器请求 Kopi Agent 代其生成文本 —— 对于需要 LLM 能力但没有自有模型访问权限的服务器非常有用。
Sampling 对所有 MCP 服务器默认启用(当 MCP SDK 支持时)。可在 sampling 键下按服务器进行配置:
mcp_servers:
my_server:
command: "my-mcp-server"
sampling:
enabled: true # Enable sampling (default: true)
model: "openai/gpt-4o" # Override model for sampling requests (optional)
max_tokens_cap: 4096 # Max tokens per sampling response (default: 4096)
timeout: 30 # Timeout in seconds per request (default: 30)
max_rpm: 10 # Rate limit: max requests per minute (default: 10)
max_tool_rounds: 5 # Max tool-use rounds in sampling loops (default: 5)
allowed_models: [] # Allowlist of model names the server may request (empty = any)
log_level: "info" # Audit log level: debug, info, or warning (default: info)
Sampling 处理器包含滑动窗口速率限制器、每请求超时限制以及工具循环深度限制,以防止滥用。指标(请求数、错误数、使用的 token 数)会按服务器实例进行跟踪。
要为特定服务器禁用 sampling:
mcp_servers:
untrusted_server:
url: "https://mcp.example.com"
sampling:
enabled: false
将 Kopi Agent 作为 MCP server 运行
除了连接到 MCP server 之外,Kopi Agent 也可以自身作为 MCP server 运行。这使得其他支持 MCP 的 agent(Claude Code、Cursor、Codex 或任何 MCP client)能够使用 Kopi Agent 的消息功能——列出会话、读取消息历史,并跨所有已连接的平台发送消息。
何时使用此功能
- 你希望 Claude Code、Cursor 或其他编码 agent 通过 Kopi Agent 发送和读取 Telegram/Discord/Slack 消息
- 你需要一个单一的 MCP server,一次性桥接到 Kopi Agent 所有已连接的消息平台
- 你已经有一个运行中的 Kopi Agent gateway,且已连接了相关平台
快速开始
kopi mcp serve
这会启动一个 stdio MCP server。MCP client(而非你)负责管理进程生命周期。
MCP client 配置
将 Kopi Agent 添加到你的 MCP client 配置中。例如,在 Claude Code 的 ~/.claude/claude_desktop_config.json 中:
{
"mcpServers": {
"hermes": {
"command": "hermes",
"args": ["mcp", "serve"]
}
}
}
或者,如果你将 Kopi Agent 安装在特定位置:
{
"mcpServers": {
"hermes": {
"command": "/home/user/.kopi/kopi-ai-agent/venv/bin/kopi",
"args": ["mcp", "serve"]
}
}
}
可用工具
该 MCP server 暴露了 10 个工具,与 OpenClaw 的 channel bridge 接口相对应,另外还包含一个 Kopi Agent 专属的 channel browser:
| 工具 | 描述 |
|---|---|
conversations_list | 列出活跃的消息会话。可按平台过滤或按名称搜索。 |
conversation_get | 通过 session key 获取某个会话的详细信息。 |
messages_read | 读取某个会话的最近消息历史。 |
attachments_fetch | 从特定消息中提取非文本附件(图片、媒体)。 |
events_poll | 从某个游标位置开始轮询新的会话事件。 |
events_wait | 长轮询/阻塞等待下一个事件到达(近实时)。 |
messages_send | 通过某个平台发送消息(例如 telegram:123456、discord:#general)。 |
channels_list | 列出所有平台上可用的消息目标。 |
permissions_list_open | 列出本次 bridge 会话中观察到的待处理审批请求。 |
permissions_respond | 批准或拒绝待处理的审批请求。 |
事件系统
该 MCP server 包含一个实时事件 bridge,它会轮询 Kopi Agent 的会话数据库以获取新消息。这让 MCP client 能够近实时地感知新到达的会话:
# Poll for new events (non-blocking)
events_poll(after_cursor=0)
# Wait for next event (blocks up to timeout)
events_wait(after_cursor=42, timeout_ms=30000)
事件类型:message、approval_requested、approval_resolved
事件队列保存在内存中,并在 bridge 连接时启动。较早的消息可通过 messages_read 获取。
选项
kopi mcp serve # Normal mode
kopi mcp serve --verbose # Debug logging on stderr
工作原理
该 MCP server 直接从 Kopi Agent 的会话存储(~/.kopi/sessions/sessions.json 以及 SQLite 数据库)读取会话数据。一个后台线程会轮询数据库以获取新消息,并维护一个内存中的事件队列。对于发送消息,它使用与定时投递和 kopi send CLI 相同的内部发送引擎(tools/send_message_tool.py)。
对于读取操作(列出会话、读取历史、轮询事件),gateway 无需运行。但对于发送操作则需要 gateway 运行,因为平台适配器需要处于活跃连接状态。
当前限制
- 内置的
kopi mcp serve目前仅暴露 stdio-only 的 MCP server。如果你需要 HTTP MCP server,请运行一个单独的适配器——或者,更常见的情况是使用 Kopi Agent 的 MCP client 端,它已经同时支持 stdio 和 HTTP(mcp_servers.yaml/config.yaml中的url+headers;参见上文的 HTTP servers)。 - 事件轮询间隔约为 200ms,通过针对 mtime 优化的数据库轮询实现(文件未变更时跳过处理)
- 尚不支持
claude/channel推送通知协议 - 仅支持发送文本(不支持通过
messages_send发送媒体/附件)