Agent X-Ray

第19章：AI 原生开发（三）—— MCP Server 详解

约 5 分钟 · 更新于 2026-09-02

Rules 和 Skills 告诉 AI"世界应该什么样"，MCP 告诉它"世界现在什么样"。Encore CLI 内置的 MCP 服务器把应用模型与运行实况——数据库 schema、服务图、分布式追踪、Pub/Sub 拓扑——直接开放给你的 AI 工具，19 个工具、零额外安装。

一、MCP 是什么，Encore 的实现有何不同

模型上下文协议 (Model Context Protocol, MCP) 是让 LLM 以标准方式访问外部数据与工具的开放协议——官方比喻是"AI 的 USB-C 接口"：AI 工具当客户端，一个本地服务器提供工具集。

Encore 的 MCP 服务器内置在 CLI 里，不需要安装任何包。它的独特底气来自第 1 章的应用模型：

"The static analyzer already builds a complete picture of your application at compile time. MCP makes that picture available to the agent."

再叠加本地真实基础设施：encore run 起的是真 Postgres——智能体看到的 schema 就是你最新迁移执行后的真实 schema，不是从代码猜的。

二、启动与接入

启动

bash

cd my-encore-app
encore mcp start

输出两种接法：

text

SSE URL:   http://localhost:9900/sse?app=your-app-id     ← SSE（Server-Sent Events）方式
Stdio:     encore mcp run --app=your-app-id              ← 标准输入输出方式

encore mcp start：起常驻 SSE 服务器（适合支持 URL 接入的工具）；
encore mcp run：以 stdio 子进程方式被 MCP 宿主拉起（多数编辑器用这种）。

接入 Cursor

项目根建 .cursor/mcp.json：

json

{
  "mcpServers": {
    "encore-local": {
      "command": "encore",
      "args": ["mcp", "run", "--app=your-app-id"]
    }
  }
}

之后 Cursor 的 agent 模式即可下达"给 pub/sub 主题加一个订阅端点"这类需要应用上下文的指令。

接入 Claude Code

bash

claude mcp add --transport stdio encore-local -- encore mcp run --app=your-app-id
claude mcp list    # 验证连接

新项目在 encore app create 选了 AI 工具时自动写好配置；存量项目 encore llm-rules init 一并生成（第 18 章）。

三、19 个工具全景（九大类）

类别	工具	给智能体什么
服务与 API	get_services	全部端点：方法、路径、请求/响应类型、鉴权配置、服务间依赖
	get_auth_handlers	鉴权处理器配置（AuthParams/AuthData 结构）
	get_middleware	中间件清单与 target 配置
数据库	get_databases	运行实例的真实 schema：表、列类型、主外键、默认值
	query_database	对本地 Postgres 直接执行 SQL
追踪	get_traces	完整分布式追踪列表（API、SQL、服务间调用、发布、出站 HTTP 全自动采集）
	get_trace_spans	单条 trace 的 span 明细：耗时、嵌套、载荷
Pub/Sub	get_pubsub	主题、发布者、订阅者、投递语义、消息类型——一次拿全拓扑
缓存与存储	get_cache_keyspaces	缓存集群与键空间定义
	get_storage_buckets / get_objects	对象桶清单与桶内容
基础设施	get_cronjobs	定时任务清单与调度
	get_metrics	应用指标
	get_secrets	密钥名字（永不返回值）
	get_metadata	完整应用元数据（应用模型全量）
源码	get_src_files	读取应用源码文件
文档	search_docs / get_docs	检索/阅读 Encore 官方文档
测试	call_endpoint	真实调用运行中应用的任意端点

与 Grep/Read 的本质差别 通用工具读代码得到的是"代码写了什么"；get_databases 返回的是迁移执行后运行实例的真实 schema，get_traces 返回的是刚才那次请求实际发生了什么。"读代码推测" vs "看运行事实"——智能体的验证能力由此质变。这也是为什么 Encore 的 MCP 比"给 AI 一个 psql 只读账号"更有价值：它还给了服务图、类型、追踪这些结构化语义。

四、四个官方工作流示例

1. 性能排查

Prompt: "The /orders endpoint is slow. Figure out why."

智能体动作链：get_traces 找最近的慢请求 → get_trace_spans 看耗时分布 → 定位（缺索引的慢 SQL / 同步调用慢下游）→ 给出修复建议。

2. 建新端点并自验

Prompt: "给已登录用户加一个订单历史端点，然后调一下并验证 trace。"

get_services 摸清架构与既有风格 → get_databases 看 orders 表真实结构 → 按约定写代码 → call_endpoint 真调一次 → get_trace_spans 确认：鉴权执行了、只查了该查的表、没有 N+1。

3. 接入 Pub/Sub

Prompt: "给 order-created 主题加一个发 Slack 通知的订阅者。"

get_pubsub 拿到主题名与消息类型 → 在正确的服务里写类型匹配的 Subscription → search_docs 查投递配置细节。

4. 数据库迁移

Prompt: "给 orders 加 shipping_address 列，跑迁移并验证。"

get_databases 看现状 → 写迁移 SQL（编号接续，第 5 章规则）→ 重启应用执行 → query_database 验证列已存在。

四个例子的共同结构：发现（get_*）→ 行动（写代码）→ 验证（call_endpoint / query_database / get_trace_spans）——第 20 章把它提炼成标准循环。

五、安全边界

只服务本地开发：MCP 伴随 encore run 的本地环境，不是生产入口；
get_secrets 只返回名字：密钥值永不过 MCP——AI 知道"应用需要 SlackWebhookURL"，但拿不到值；
破坏半径 = 本地：query_database / call_endpoint 操作本地实例，AI 最坏也就是弄脏本地库（encore db reset 一条命令恢复）——这恰好构成一个安全的"AI 试验场"。

团队补充约定（建议）：本地库不要放生产数据导出；上游联调凭据用测试环境的（本机 B2B 项目即全程用 fticketdev 测试网关凭据）。

六、MCP 之外：别忘了它的搭档

MCP 给实况，但约定仍靠 Rules/Skills：没有它们，智能体拿着 get_services 的结果也可能用错误语法写新端点。官方推荐两者组合（第 18 章 + 本章 = 完整配置），组合后的工作流是第 20 章的主题。

七、常见误区

忘了先 encore run——应用没跑起来，schema/trace 类工具无数据可查。
--app 填错 app id——多项目机器上连到别的应用（app id 看 encore.app 或 encore app create 输出）。
用 MCP 查生产问题——它只连本地；生产观测走 Cloud Dashboard / 自有观测栈。
担心 AI 通过 MCP 偷密钥——get_secrets 只有名字；真正要防的是本地库里的敏感数据（别放生产导出）。
只装 MCP 不装 Rules/Skills——实况 + 错误语法 = 自信地写错。
认为 call_endpoint 是 mock——它是真调用，有副作用（写库、发事件），设计验证步骤时要心里有数。

八、实践练习

在第 14 章的 uptime 项目上 encore mcp start，把它接入你在用的 AI 工具（Cursor 或 Claude Code），claude mcp list 或工具面板确认连接。
让 AI 用 get_services + get_pubsub 口头描述这个应用的架构，对照 Encore Flow 面板验证它说得对不对。
复现工作流 2：让 AI 加一个"查询某站点最近 10 次巡检记录"的端点，要求它调用后用 trace 验证只查了 checks 表。
复现工作流 4：让 AI 给 site 表加 note 列（迁移 + 验证），检查它的迁移文件编号是否接续。
手动做一次工作流 1：自己在 SQL 里塞 pg_sleep(1) 制造慢端点，让 AI 通过 trace 找出来。

九、总结

Encore MCP 内置于 CLI：encore mcp start（SSE）/ encore mcp run（stdio），Cursor 与 Claude Code 各一段配置接入。
19 个工具九大类，核心四组：结构（services/pubsub/metadata）、数据（databases/query）、行为（traces/spans）、行动（call_endpoint）。
独特价值 = 应用模型（编译期全图）+ 本地真实基础设施（运行期事实）。
安全边界清晰：仅本地、密钥只露名、破坏半径可一键重置。
工作流骨架"发现→行动→验证"，与 Rules/Skills 组合才完整——见下一章。

请继续阅读：第20章:AI 原生开发（四）实战工作流。

原始资料引用

本章目录

一、MCP 是什么，Encore 的实现有何不同二、启动与接入三、19 个工具全景（九大类）四、四个官方工作流示例五、安全边界六、MCP 之外：别忘了它的搭档七、常见误区八、实践练习九、总结原始资料引用 Related Documents