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

# 用 MCP 连接 Server

> 用 Agent 的工具连上刚才那套数据。MCP 不是完整 HTTP API。

MCP 是给 Agent 明确调用的工具。它连的是同一个 Server、同一套数据，**不是**完整 HTTP API。

自动召回、采集和刷新仍由宿主 Hook 或框架适配器负责。MCP 只露出你需要亲自调用的那些操作。

![同一套数据，三个入口：HTTP、Python Client 和 MCP。覆盖面不一样。](https://mintcdn.com/powercontext/1t_ajifOEOG5YQjP/assets/basic-mcp-surface-zh.svg?fit=max\&auto=format\&n=1t_ajifOEOG5YQjP\&q=85\&s=795713f330fa011be869c03a802a1002)

> [!NOTE]
>
> 接口字段和错误码以 [官方文档](https://oceanbase.github.io/powercontext/) 的最新发布版本为准。这页只帮你连上 `/mcp`，并分清它能做什么。

## 默认地址

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
http://127.0.0.1:8000/mcp
```

这是 Streamable HTTP。默认只听本机回环地址，未开 Bearer。Server 没启动时，客户端应看到连接失败，而不是一套看起来正常的空工具。

## 最小客户端配置

把下面这段合并进 Agent 的 MCP 配置。不要写本机绝对路径，也不要把令牌放进 URL。

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

有的 Agent 把类型写成 `streamable-http`。指向同一个 `/mcp` 即可。Codex、Claude Code、WorkBuddy 的字段名和请求头辅助程序不同，那些细节在对应页面。

## 能做 / 不能做

MCP 刻意只开放 HTTP 能力的一部分。用这张表判断下一步还能不能留在 Agent 里做，还是要换到 Python Client 或 HTTP。

| 能做 | 不能做 |
| - | - |
| `remember_memory`、`search_memory`、精确读取 / 列出 / 修订 / 停用 | `prepare_context`。最终 `PreparedContext` 通常由 Hook 或适配器在请求时准备 |
| `capture_content_source` | `flush_memory` |
| 工作契约（Work Contract）、Handoff (把当前目标、已验证进度、阻塞项和下一步交给接手者。不提交就还是临时包。)、Task Outcome | Skill 生成 / 导出 |
| Candidate 列出 / 读取 / 批准 / 拒绝 / 修订 | Experience 操作 |
| 与 HTTP、Python Client 读写同一套数据 | 复现每个集成的自动召回 / 采集 / 刷新 |

当前测试里的默认 MCP 工具名就是上表这些操作 id。Handoff report 相关只读工具只在该功能打开时出现，不要当成默认面。

MCP 上的 `readOnlyHint` / `destructiveHint` 只给 Agent 做确认提示。它**不是**授权边界。提案 Agent 仍可能同时拿到批准工具，除非宿主自己撤权。

> [!WARNING]
>
> `handoff_current_work` 会写一条边界 Source。讨论设计，或说 `preview and make no writes`，都不要调用它。

## 开启 Bearer 之后

默认本机回环地址可以关认证。一旦 `POWERCONTEXT_SERVER_AUTH_ENABLED=true`：

* `/mcp` 本身要带 `Authorization: Bearer <token>`，发现和工具调用都算；
* `/openapi.json` 同样要请求头；
* `/docs` 仍可公开打开，那不代表 MCP 或 API 已经授权。

不要把令牌放进 URL。用该 Agent 自己的请求头辅助程序或环境变量，例如 Codex 的 `POWERCONTEXT_CODEX_AUTHORIZATION`。

401/403 不是 `empty`。工具失败必须看得见，不能假装写入成功。

## 怎么知道跑通了

* 客户端连上 `http://127.0.0.1:8000/mcp`，能列出 `remember_memory` 和 `search_memory`。
* 你用 MCP 写下的 Memory，能被 [常用 API 串讲](https://powercontext.mintlify.site/zh/basic-usage/api-tour.md) 的 Python Client 搜到。
* 工具列表里没有 `prepare_context`。
* 停掉 Server 后再调用 `remember_memory`，失败看得见。
* 开了 Bearer 后，不带请求头的 `/mcp` 不能当成已连接。

> [!TIP]
>
> 自动帮你找回上下文失败时，当前任务还应继续。你明确要求写入 Memory、提交 Handoff、批准或导出时，失败必须能看见。完整说明见 [fail-open](https://powercontext.mintlify.site/zh/mental-model/fail-open.md)。

## 下一步

> [card] [用 Dashboard 核对数字](https://powercontext.mintlify.site/zh/basic-usage/dashboard.md)
>
> 配上和客户端相同的 Scope，核对统计是否一致。

> [card] [编程 Agent 怎么注册 MCP](https://powercontext.mintlify.site/zh/coding-agents/overview.md)
>
> Codex、Claude Code 的字段名不同。便携路径看 [Agent Plugin](https://powercontext.mintlify.site/zh/common-agents/agent-plugin.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.