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

# 首个 MCP

> 创建一个演示数学 Toolkit，将其持久化到 HeavenBase 的 Capsule 注册表，并在任意位置通过 MCP 提供服务。

<Note>
  *MCP 服务器让你不必重复造轮子。我们也希望你不必重复安装轮子。*
</Note>

大多数 MCP 服务器会定义函数然后启动进程。HeavenBase 增加了注册表持久化：Toolkit 的源代码、签名、文档字符串与修订历史都会记录在 Capsule 注册表中。注册一次后，即便原始 `.py` 文件已删除，你也可以通过简短脚本或 CLI 提供服务。

<br />

## 1. 演示：创建数学 Toolkit

定义普通函数并以列表传入。HeavenBase 使用每个函数的 `__name__` 作为工具名称：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# math_tools.py
import heavenbase as hb


def add(left: int, right: int) -> int:
    """Add two numbers."""
    return left + right


def sub(left: int, right: int) -> int:
    """Subtract right from left."""
    return left - right


def mul(left: int, right: int) -> int:
    """Multiply two numbers."""
    return left * right


def div(left: int, right: int) -> float:
    """Divide left by right."""
    return left / right


def mod(left: int, right: int) -> int:
    """Return left modulo right."""
    return left % right


def fibonacci(n: int) -> list[int]:
    """Return the first n Fibonacci numbers."""
    a, b = 0, 1
    result = []
    for _ in range(n):
        result.append(a)
        a, b = b, a + b
    return result

if __name__ == "__main__":
    toolkit = hb.Toolkit(
        "math-tools",
        [add, sub, mul, div, mod, fibonacci],
        description="Basic arithmetic and sequence operations",
        namespace="quickstart",
        version="1",
    )

    toolkit.register(overwrite=True, reason="initial quickstart math tools")
```

<Info>
  传入函数**列表**是最简单的形式：函数的 `__name__` 成为工具名称，文档字符串成为工具描述。若需自定义名称，可传入字典，例如 `{"add": add, "mul": mul}`。HeavenBase 会自动捕获源代码、类型注解与 import 引用。`namespace="quickstart"` 参数将此演示工具集 (Toolkit) 归入 `quickstart` 注册表前缀，便于 `hb mcp list` 与 serve 命令定位 `quickstart.math-tools`。`reason` 值是人类可读的注册表修订说明，便于日后查看 Toolkit 历史。
</Info>

<br />

## 2. 运行一次以持久化

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
python math_tools.py
```

此时 Toolkit 已校验并写入注册表。你可以删除 `math_tools.py`；这些函数现已存在于注册表中。

这种持久化是关键区别。注册完成后，可在另一脚本中提供服务、重启后继续，或在共享注册表数据库时在另一台机器上提供服务。

<br />

## 3. 在任意位置加载并提供服务

Toolkit 持久化后，加载与提供服务无需函数定义，也无需从原始模块 import：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# serve_math.py
import heavenbase as hb

loaded = hb.Toolkit.load(name="math-tools", namespace="quickstart", version="1")
print(loaded.to_mcp_json())
loaded.serve(wait=True)
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
python serve_math.py
```

服务器会打印 MCP 配置并在 `http://127.0.0.1:7001/mcp` 监听：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mcpServers": {
    "math-tools": {
      "transport": "http",
      "url": "http://127.0.0.1:7001/mcp"
    }
  }
}
```

HeavenBase 支持常见的 MCP 传输方式。每个服务器进程使用一种传输，客户端连接对应端点：

| Transport       | Serve command                                         | Client endpoint             |
| --------------- | ----------------------------------------------------- | --------------------------- |
| Streamable HTTP | `hb mcp serve quickstart.math-tools --transport http` | `http://127.0.0.1:7001/mcp` |
| SSE             | `hb mcp serve quickstart.math-tools --transport sse`  | `http://127.0.0.1:7001/sse` |
| stdio           | `hb mcp stdio quickstart.math-tools`                  | command transport, no URL   |

在 Python 中，当仅支持 SSE 的客户端需要 `/sse` 时，向 `loaded.to_mcp_json(transport="sse")` 与 `loaded.serve(transport="sse", wait=True)` 传入相同传输参数。

<Note>
  将注册与服务拆成两个脚本是有意为之：这表明 Toolkit **比**创建它的脚本更长寿。HeavenBase 的注册表将创建与服务解耦，因此同一已注册的 Toolkit 可由任何能读取注册表 DB 的进程提供服务。若更看重便利，也可在一个文件中合并两步。
</Note>

<br />

## 4. 直接从 CLI 提供服务

完全跳过服务器脚本。CLI 可加载并提供任何已持久化的 Toolkit：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb mcp serve quickstart.math-tools
```

无需编写服务器代码即可列出、检查并调用工具：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb mcp list
hb mcp tools quickstart.math-tools
hb mcp call quickstart.math-tools add --args '{"left": 2, "right": 3}'
hb mcp mcp-json quickstart.math-tools
```

`call` 命令应打印 `5`；`mcp-json` 应打印与上文相同的 HTTP 配置。

<br />

## 5. 连接你的 Agent

将服务器添加到你常用的编程 Agent：

<Tabs>
  <Tab title="Claude Code">
    使用 Claude Code CLI 添加 HTTP 服务器：

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    claude mcp add --transport http math-tools http://127.0.0.1:7001/mcp
    claude mcp list
    ```

    Claude Code 将本地作用域的 MCP 服务器存储在 `~/.claude.json`。若需在仓库内共享，请在项目根目录用相同命令加 `--scope project`，或创建 `.mcp.json`：

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "math-tools": {
          "type": "http",
          "url": "http://127.0.0.1:7001/mcp"
        }
      }
    }
    ```

    启动新的 Claude Code 会话，运行 `/mcp`，确认 `math-tools` 已连接，再请 Agent 使用算术工具。
  </Tab>

  <Tab title="Codex">
    Codex 支持三种方式：CLI、配置文件与 GUI（Codex App 或 IDE 扩展）。

    GUI（Codex App）：Settings > MCP servers > + Add server，然后填写：

    * **Name:** `math-tools`
    * 选择 **Streamable HTTP**
    * **URL:** `http://127.0.0.1:7001/mcp`

    配置文件（`~/.codex/config.toml`）：

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    [mcp_servers.math-tools]
    url = "http://127.0.0.1:7001/mcp"
    ```

    CLI：

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    codex mcp add math-tools --url http://127.0.0.1:7001/mcp
    codex mcp list
    ```

    <Note>
      若你的 Codex 版本在添加后未显示 HTTP MCP 服务器，请在 `~/.codex/config.toml` 中启用 `experimental_use_rmcp_client` 功能：

      ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
      [features]
      experimental_use_rmcp_client = true
      ```
    </Note>

    启动新的 Codex 会话，或在 TUI 中运行 `/mcp`，确认 `math-tools` 出现并已发现其工具。
  </Tab>

  <Tab title="Cursor">
    若服务器只属于一个仓库，使用项目级配置；若希望全局可用，使用全局配置：

    * **Project:** `.cursor/mcp.json`
    * **Global:** `~/.cursor/mcp.json`

    粘贴以下配置：

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "math-tools": {
          "type": "http",
          "url": "http://127.0.0.1:7001/mcp"
        }
      }
    }
    ```

    也可打开 Cursor Settings > Features > MCP > Add new global MCP server，然后填写：

    * **Name:** `math-tools`
    * **Type:** `http`
    * **URL:** `http://127.0.0.1:7001/mcp`

    重新加载 Cursor 或打开新对话，然后在 MCP 设置面板中确认 `math-tools` 已启用。
  </Tab>

  <Tab title="VS Code / Copilot">
    按 `Ctrl+Shift+P`（Windows/Linux）或 `Cmd+Shift+P`（macOS），运行 **MCP: Add Server**，选择 **HTTP**，然后填写：

    * **URL:** `http://127.0.0.1:7001/mcp`
    * **Name:** `math-tools`

    若需工作区作用域，添加 `.vscode/mcp.json`。VS Code 使用 `servers` 键，而非 `mcpServers`：

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "servers": {
        "math-tools": {
          "type": "http",
          "url": "http://127.0.0.1:7001/mcp"
        }
      }
    }
    ```

    重新加载 VS Code 窗口，或从命令面板运行 **MCP: List Servers**，然后确认 `math-tools` 正在运行。
  </Tab>

  <Tab title="OpenCode">
    将远程 MCP 服务器添加到项目 `opencode.json` / `opencode.jsonc`，或添加到全局配置 `~/.config/opencode/opencode.json`：

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "math-tools": {
          "type": "remote",
          "url": "http://127.0.0.1:7001/mcp",
          "enabled": true
        }
      }
    }
    ```

    在 Windows 上，全局配置使用 `%APPDATA%\opencode\config.jsonc`。重启 OpenCode 或运行 `opencode mcp list` 确认服务器可用，然后在提示中引用 `math-tools`。
  </Tab>

  <Tab title="OpenClaw">
    在 `~/.openclaw/openclaw.json` 的 `mcp.servers` 下添加服务器：

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcp": {
        "servers": {
          "math-tools": {
            "url": "http://127.0.0.1:7001/mcp",
            "transport": "streamable-http"
          }
        }
      }
    }
    ```

    或用 CLI 写入相同条目：

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    openclaw config set mcp.servers.math-tools '{"url":"http://127.0.0.1:7001/mcp","transport":"streamable-http"}'
    openclaw mcp list
    ```

    OpenClaw 会热应用大多数 MCP 配置变更。若已有会话已加载工具，请启动新的 Agent 会话。
  </Tab>

  <Tab title="Hermes">
    将 HTTP 服务器添加到 `~/.hermes/config.yaml`：

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    mcp_servers:
      math-tools:
        url: "http://127.0.0.1:7001/mcp"
        enabled: true
    ```

    保存文件后重新加载或重启 Hermes，然后请其列出可用 MCP 工具，确认算术工具已出现。
  </Tab>

  <Tab title="LM Studio">
    在 LM Studio 中打开 Program/Developer 面板，选择 **Install > Edit mcp.json**，并添加服务器。LM Studio 采用与 Cursor 相同的 `mcp.json` 写法：

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "mcpServers": {
        "math-tools": {
          "type": "http",
          "url": "http://127.0.0.1:7001/mcp"
        }
      }
    }
    ```

    保存文件，若 LM Studio 显示开关则启用服务器，并开启工具使用的新对话。
  </Tab>

  <Tab title="HeavenBase">
    HeavenBase 自带 LLM 聊天/会话界面，可用 `--mcp` 直接从注册表连接 MCP 服务器：

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    hb llm chat --mcp quickstart.math-tools "What's 42 * 73?"
    hb llm session --mcp quickstart.math-tools
    ```

    也可让 HeavenBase 指向正在运行的 HTTP MCP 端点：

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    hb llm session --mcp http://127.0.0.1:7001/mcp
    ```

    在交互式会话中，用 `/mcp SOURCE` 添加另一个 MCP 源。
  </Tab>

  <Tab title="OpenAI Agents SDK">
    安装 SDK，用 Streamable HTTP 启动 HeavenBase 服务器，然后用 `MCPServerStreamableHttp` 连接：

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    pip install openai-agents
    hb mcp serve quickstart.math-tools --transport http
    ```

    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    from agents import Agent, ModelSettings, OpenAIChatCompletionsModel, Runner
    from agents.mcp import MCPServerStreamableHttp

    import heavenbase as hb

    async with MCPServerStreamableHttp(
        name="math-tools",
        params={"url": "http://127.0.0.1:7001/mcp"},
        cache_tools_list=True,
    ) as server:
        llm = hb.LLM(preset="chat")
        model_args = llm.to_args()
        model_name = model_args.pop("model")

        agent = Agent(
            name="MathAgent",
            instructions="Use the MCP math tools when they help.",
            model=OpenAIChatCompletionsModel(
                model=model_name,
                openai_client=llm.to_aclient(),
            ),
            model_settings=ModelSettings(**model_args),
            mcp_servers=[server],
            mcp_config={"include_server_in_tool_names": False},
        )

        result = await Runner.run(agent, "What's 42 * 73?")
        print(result.final_output)
    ```

    若你的 SDK 版本仅提供 `MCPServerSse`，请用 `hb mcp serve quickstart.math-tools --transport sse` 启动 HeavenBase，并连接 `http://127.0.0.1:7001/sse`。
  </Tab>
</Tabs>

<br />

## 6. 动手试试

连接后，请 Agent 使用数学工具：

```
> What's 42 * 73?
> Compute the first 15 Fibonacci numbers.
> What is the 63rd Fibonacci number modulo 10000?
> Is 97 a prime number? (use mod to check divisibility)
> Calculate (85 + 37) * 12 / 4
```

Agent 通过 MCP 发现每个工具的名称、描述与参数 schema，再按需调用。

<Note>
  由于 Toolkit 已持久化，你可以停止服务器、重启，然后用 `hb mcp serve quickstart.math-tools` 恢复：无需脚本、无需重新定义、不会丢失。
</Note>

<br />

## 进一步探索

<Tip>
  **下一步：**

  * [HeavenBase MCP](/zh/quickstart/heavenbase-mcp) - 通过 MCP 暴露工作区，无需编写实体代码
  * [30 分钟开发者工作坊：任务清单管理器](/zh/quickstart/sublinear-workshop) - 构建 Sublinear，一款 Agent 化任务清单管理器
  * [工具集 (Toolkit)](/zh/features/toolkits) - 工具集 (Toolkit) 架构、MCP 提供与导入
  * [Capsule](/zh/features/capsules) - 持久化任意 Python 函数
  * [MCP 工具集 (Toolkit) 参考](/zh/reference/mcp-toolkit/overview) - 完整工具列表与服务选项
</Tip>

<br />