---
title: "MCP 集成 · Finch Agent"
description: "声明式贡献 MCP server，按需加载工具"
source: https://finchwork.app/zh/docs/minitools-mcp
---

# MCP 集成

MCP 集成是 capability 机制的典型应用：官方 MCP Client 小程序提供 `mcp.client`，其他小程序消费它。

## 什么时候选 MCP

-   工具集很大（10+）且多数不常同时使用，希望 Finch 按需加载。
-   目标服务已有官方 MCP SDK，不想重写一遍。

## 两层设计

**静态层**（`finch.json`）只放元数据，**绝不放密钥**：

```json
{
  "requires": { "capabilities": ["mcp.client"] },
  "contributes": {
    "mcpServers": [
      { "name": "my-server", "description": "My MCP server." }
    ]
  }
}
```

**运行时层**在 `activate()` 里提供真正的传输配置：

```ts
async function registerWhenReady(ctx: finch.MiniToolContext, apiKey: string) {
  // MCP Client 可能晚于本工具激活，短轮询等待
  for (let i = 0; i < 20; i++) {
    if (ctx.capabilities.has('mcp.client')) break;
    await new Promise((r) => setTimeout(r, 250));
  }
  if (!ctx.capabilities.has('mcp.client')) return;

  const mcp = ctx.capabilities.get('mcp.client');
  await mcp.registerServer({
    name: 'my-server',
    command: 'npx',
    args: ['-y', 'my-mcp-server'],
    env: { API_KEY: apiKey },
    ownerExtensionId: ctx.minitool.id,
  });
}
```

运行时注册是内存态的，每次激活都要重新执行。

## 密钥怎么来

标准做法：提供一个 `setup_*` 工具或设置菜单项，用表单收集密钥 → 存 `ctx.secrets` → 调用 `registerServer()`。详见《[账号、配置与 OAuth 登录](/zh/docs/minitools-oauth)》。