AB
AiBoss
チュートリアル

设计只做集成的 MCP 服务器:把决策循环留在宿主侧

チュートリアル

设计只做集成的 MCP 服务器:把决策循环留在宿主侧

MCP 服务器该做到哪一步就停?这篇教程从一段只读服务目录代码出发,讲清如何用窄工具、资源与提示词把 MCP 当作集成边界,把规划、状态、授权与审批留在宿主应用,并给出完整可运行的 Python 示例与边界处的失败、鉴权、注入处理要点。

MCP 项目通常会在某个时刻开始变得模糊。多数情况下,这个时刻出现在第一次成功调用工具之后不久。设想一个服务目录,里面放着工程组织日常维护的东西:负责人、直接依赖、运行手册链接。宿主应用已经可以问目录「checkout 归谁负责」。接着有人提出一个更「好用」的体验:既然 checkout 依赖 payments,服务器能不能顺便把 payments 也查了;能不能自己判断这次查询是否与某起事故相关;能不能调用一个模型,用让人安心的语气把答案写出来。用不了多久,这个服务器就不再只是暴露目录,而是在做规划、保存对话状态、挑选后续调用,甚至去获取原本属于宿主的凭据。

这些步骤单看都不荒唐,每一个都能让演示显得更强。问题在于它们叠加起来,等于在协议端点背后藏了第二个应用。另一个宿主连上同一个服务器,就会继承它的规划器、它的模型选择、它对「接下来该发生什么」的理解。这种便利的代价很高。

这篇教程的立场刻意收得很窄:MCP 通常应当被当作一条集成边界。它标准化的是宿主如何发现并调用外部能力,它并不提供一套智能体架构。除非服务器有独立站得住脚的理由,否则决策循环、用户交互、持久工作流状态,以及有后果动作的授权,都应该留在宿主侧。这不是说 MCP 规范禁止服务器里写智能体逻辑,而是一个架构判断:当第一次有用的集成变成共享基础设施之后,组织还能在哪里看见、测试并修改自己的决策。

下面按「先定边界,再写代码,最后处理边界处的麻烦」的顺序展开。示例使用 Python 3.11 及以上版本与官方 Python SDK v2,其中的类名、参数与行为以你安装时官网当前信息为准。

准备工作

开始之前,先把环境和前置条件确认清楚。这一步做扎实,后面的边界讨论才有落点。

  • Python 运行时:示例代码面向 Python 3.11+,用到了 from __future__ import annotations、dataclass(frozen=True) 与内置泛型写法。低于这个版本会在类型注解和部分语法上出问题。
  • 官方 Python SDK v2:示例使用 SDK 的高层服务器类 MCPServer。在 v1 里这个类叫 FastMCP,如果你照着旧资料写代码,导入路径和类名会对不上。安装方式与包名以官网当前信息为准。
  • 传输方式:示例以 stdio 运行,也就是由宿主进程拉起服务器子进程,通过标准输入输出交换协议消息。这意味着 stdout 必须留给协议消息,任何调试打印都要走 stderr,否则会污染协议流。
  • 不需要的东西:这个服务器里没有模型客户端、没有规划器、没有数据库、没有部署框架。这不是省略,而是设计目标本身。
  • 协议版本认知:较新的协议修订(素材提到 MCP 2026-07-28)移除了早期的 initialize/initialized 握手与 Mcp-Session-Id 头,请求在 _meta 中携带协议版本与客户端元数据,客户端可以先通过 server/discover 获取服务器能力。具体字段与可用性请以官网当前信息为准。要点是:协议核心变成无状态,不等于业务应用无状态。

还有一项准备工作是概念上的:先想清楚这个服务器要暴露哪几类原语。SDK 对三类服务器原语的定位很有用——工具由模型控制,资源由应用控制,提示词由用户控制。模型并不直接连到目录服务器;它可能帮助宿主挑选工具,宿主也完全可以用一条不含模型的确定性流程。无论哪种情况,客户端都在宿主一侧,由宿主决定某次调用是否被允许,以及结果在更大的请求里意味着什么。

操作步骤

第一步:先写下边界,再写代码

动手之前,把「服务器负责什么、宿主负责什么」写成两列。判断标准可以借用素材里的提问方式:一个用户问「checkout 归谁负责,它依赖什么」。宿主 A 可能选择发两次调用,一次取负责人,一次取直接依赖;宿主 B 可能只需要负责人,因为它在填一张表单;宿主 C 可能在跑一条确定性的事故流程,只有在调用方选定了环境之后才允许查询依赖。这些是同一能力的不同应用,不是目录的不同版本。

一旦服务器里装了规划器,它就得回答一些它并不适合回答的问题:用户是否真的批准了写操作?这个宿主被允许连接哪些服务器?用户整个请求的截止时间是什么,而不只是这一次查询的?模型是否应该拿到原始结果?如果下一步判断错了,运维人员去哪里找解释?把这些问题藏进 tools/call 背后,一个都不会变小。

确实存在例外:服务器可以合理地封装一个必须作为单一领域服务来运营的专门工作流,也可以在受限的转换环节里委托给模型。但例外需要有名字、有负责人、有权限模型。「这是一个给智能体用的 MCP 服务器」不构成理由。

第二步:定义领域数据与查找逻辑

示例用一个只读的目录夹具,包含四个服务:checkout、payments、inventory、ledger。数据结构用冻结的 dataclass,查找逻辑集中在一个函数里,空值和未知服务都转成 SDK 的 ToolError。

# service_catalog_server.py
from __future__ import annotations

from dataclasses import asdict, dataclass

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError


@dataclass(frozen=True)
class Service:
    name: str
    owner: str
    dependencies: tuple[str, ...]
    runbook_url: str


CATALOG: dict[str, Service] = {
    "checkout": Service("checkout", "commerce-platform", ("payments", "inventory"), ""),
    "payments": Service("payments", "payments-platform", ("ledger",), ""),
    "inventory": Service("inventory", "supply-platform", (), ""),
    "ledger": Service("ledger", "finance-platform", (), ""),
}


def find_service(service: str) -> Service:
    normalized = service.strip().lower()
    if not normalized:
        raise ToolError("service must not be empty")
    try:
        return CATALOG[normalized]
    except KeyError as exc:
        raise ToolError(f"unknown service: {normalized}") from exc

这里有两个细节值得注意。第一,规范化(去空白、转小写)属于领域逻辑,放在服务器里是对的——目录服务最清楚名字该怎么归一。第二,预期内的领域失败用 ToolError 表达,而不是让 KeyError 直接冒出去。前者会变成客户端可预期的错误结果,后者属于另一类失败。

第三步:创建服务器并写清使用说明

服务器实例上可以带一段 instructions,用来约束调用方如何使用这些工具。示例里的说明是:目录工具只用于服务元数据;当查找没有结果时,不要推断负责人或依赖关系。

mcp = MCPServer(
    "service-catalog",
    instructions=(
        "Use catalogue tools only for service metadata. "
        "Do not infer ownership or dependencies when a lookup returns no result."
    ),
    version="0.1.0",
)

版本号、参数名与默认值请以官网当前信息为准。这段说明本身不执行任何策略,它只是给宿主和模型提供上下文;真正的允许与拒绝仍然发生在宿主侧。

第四步:用窄工具暴露能力

两个工具,各自只做一件事,返回结构化字段而不是散文。

@mcp.tool()
def get_service_owner(service: str) -> dict[str, str]:
    """Return the owning team and runbook URL for one catalogue service."""
    entry = find_service(service)
    return {
        "service": entry.name,
        "owner": entry.owner,
        "runbook_url": entry.runbook_url,
    }


@mcp.tool()
def list_service_dependencies(service: str) -> dict[str, object]:
    """Return direct dependencies only; this does not calculate a transitive graph."""
    entry = find_service(service)
    return {"service": entry.name, "dependencies": list(entry.dependencies)}

装饰器会根据 Python 类型注解推导工具的参数 schema,函数文档字符串则成为工具描述的一部分,所以描述要写准。这里有两个刻意的设计选择:

  • 返回结构化字段。宿主不需要先从一句话里把负责人「抠」出来,才能渲染界面或施加策略。
  • 依赖工具只承诺直接依赖。传递闭包的图遍历在成本、失败模式和新鲜度语义上都不同,如果确实需要,应当是一个单独命名的契约,而不是悄悄塞进这个工具里。

第五步:把参考数据做成资源

完整目录适合作为资源暴露,而不是再开一个「顺手取全部」的工具。资源代表应用可以选择加载的参考数据。

@mcp.resource("service-catalog://overview", mime_type="application/json")
def catalogue_overview() -> dict[str, object]:
    """Read the complete illustrative catalogue as reference data."""
    return {"services": [asdict(service) for service in CATALOG.values()]}

这里显式声明了 application/json 媒体类型。一个返回字典的资源会被序列化成 JSON,但如果不声明,它仍会被当作纯文本对外通告,宿主在解析时就会多一层猜测。

第六步:提供一个有边界的提示词

提示词由用户控制,它只生成一段有边界的指令脚手架,既不调用模型,也不把一个问题变成不受控的调查。

@mcp.prompt()
def investigate_service(service: str) -> str:
    """Create a bounded checklist for investigating a service."""
    return (
        f"Investigate the service named {service!r}.\n"
        "First retrieve its owner and direct dependencies from the service catalogue.\n"
        "State unknowns explicitly.\n"
        "Do not propose or perform a change."
    )

宿主可以把这段提示词提供给用户,同时施加自己的工具策略,并在事实回来之后决定是否值得采取任何动作。提示词里明确写了「不要提议或执行变更」,但同样地,这句话是给人和模型看的约束,不是强制机制。

第七步:以 stdio 启动

if __name__ == "__main__":
    mcp.run()  # stdio: reserve stdout for protocol messages

启动后,宿主进程通过标准输入输出与它通信。再次强调:stdout 只留给协议消息,调试输出走 stderr。

一个完整示例

把上面的片段合成一个文件,就是一个可以跑通的最小服务器。完整代码如下:

# service_catalog_server.py
from __future__ import annotations

from dataclasses import asdict, dataclass

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError


@dataclass(frozen=True)
class Service:
    name: str
    owner: str
    dependencies: tuple[str, ...]
    runbook_url: str


CATALOG: dict[str, Service] = {
    "checkout": Service("checkout", "commerce-platform", ("payments", "inventory"), ""),
    "payments": Service("payments", "payments-platform", ("ledger",), ""),
    "inventory": Service("inventory", "supply-platform", (), ""),
    "ledger": Service("ledger", "finance-platform", (), ""),
}

mcp = MCPServer(
    "service-catalog",
    instructions=(
        "Use catalogue tools only for service metadata. "
        "Do not infer ownership or dependencies when a lookup returns no result."
    ),
    version="0.1.0",
)


def find_service(service: str) -> Service:
    normalized = service.strip().lower()
    if not normalized:
        raise ToolError("service must not be empty")
    try:
        return CATALOG[normalized]
    except KeyError as exc:
        raise ToolError(f"unknown service: {normalized}") from exc


@mcp.tool()
def get_service_owner(service: str) -> dict[str, str]:
    """Return the owning team and runbook URL for one catalogue service."""
    entry = find_service(service)
    return {
        "service": entry.name,
        "owner": entry.owner,
        "runbook_url": entry.runbook_url,
    }


@mcp.tool()
def list_service_dependencies(service: str) -> dict[str, object]:
    """Return direct dependencies only; this does not calculate a transitive graph."""
    entry = find_service(service)
    return {"service": entry.name, "dependencies": list(entry.dependencies)}


@mcp.resource("service-catalog://overview", mime_type="application/json")
def catalogue_overview() -> dict[str, object]:
    """Read the complete illustrative catalogue as reference data."""
    return {"services": [asdict(service) for service in CATALOG.values()]}


@mcp.prompt()
def investigate_service(service: str) -> str:
    """Create a bounded checklist for investigating a service."""
    return (
        f"Investigate the service named {service!r}.\n"
        "First retrieve its owner and direct dependencies from the service catalogue.\n"
        "State unknowns explicitly.\n"
        "Do not propose or perform a change."
    )


if __name__ == "__main__":
    mcp.run()

现在回到最初那个问题,看宿主这一侧发生了什么。宿主先确认调用方身份和整体截止时间,选择一个被允许连接的 MCP 服务器。如果策略允许这个请求,它调用 get_service_owner("checkout"),结果返回 commerce-platform。只有在这之后,它才决定是否需要直接依赖,并调用 list_service_dependencies("checkout")。

服务器只做了被要求做的事:它没有假定依赖总是需要,没有把数据发给模型,也没有把一次读取变成事故流程。正是这种克制,让同一个服务器可以同时服务于聊天应用、命令行工具、事故控制台和测试脚手架。

在远程部署下,无状态的协议核心意味着一个请求可能落到任意一个合适的副本上。这在运维上有用,但不应被过度解读:目录适配器仍然需要自己的连接池、超时行为、缓存规则和一致性模型;宿主与服务器仍然需要就身份和权限达成一致。轮询负载均衡器提供不了这些缺失的决策。

失败处理遵循同样的区分。格式错误或未知的服务标识应当产生可预期的错误策略;一个缓慢的目录 API 应当消耗请求剩余的截止时间,而不是开启一段新的、无界的等待。示例对预期内的领域失败抛出 SDK 的 ToolError,在锁定的 SDK 版本下,客户端会收到 is_error=True 的工具结果。未预期的异常属于另一类失败,不应成为意外泄露内部信息的途径。

注意事项

边界在尴尬的地方才真正显现。以下几条是素材明确点出的限制与坑,落地时逐条对照。

本地示例没有鉴权,不要照搬到远程

这个 stdio 示例不认证调用方,也不包含敏感数据。把这种「没有」复制到一个远程目录服务器上,属于范畴错误。对远程服务器,宿主应当选择可信端点,并把已认证的调用方带入一个针对具体动作和租户的授权决策。能连上 MCP 端点,本身并不等于有权读取每一个资源或调用每一个工具。

写操作需要额外的一整套东西

对写操作,边界需要的不只是「调用成功」:一个明确的批准决定、在可能重试时使用的幂等键、请求截止时间,以及绑定到预期操作的审计记录。模型的偏好既不是同意,也不是授权。

把工具返回内容当作来自另一信任边界的数据

服务器的描述、运行手册和工具结果,都可能包含试图重定向宿主或模型的文本。处理方式包括:保留来源信息、限制输出大小、在记录日志前脱敏敏感字段,以及把「提供的事实」与「宿主愿意遵循的指令」区分开。

协议无状态不等于应用无状态

较新的协议修订移除了会话头,让协议核心变成无状态。但一个会创建持久对象的工作流仍然需要显式标识符和一个所有权清晰的数据存储。从工具返回一个请求 ID、在后续调用中再传回来,比让应用状态消失在传输会话里更容易审查。协议只是移走了一个诱人的藏身处,并没有消除设计状态的需要。

不要用服务器替宿主做规划

一旦服务器里出现规划器,它就要替宿主回答批准、权限、截止时间、模型输入和可解释性这些问题。这些问题不会因为被藏进 tools/call 而变小。把决策循环、用户交互、持久状态和授权留在宿主侧,是让组织在集成变成共享基础设施之后仍能看见、测试和修改决策的前提。

易变信息以官网为准

SDK 的类名(v1 的 FastMCP 与 v2 的 MCPServer)、协议修订号、字段名、安装方式与配额限制都可能变化。本文示例基于素材给出的版本形态,实际落地前请核对官网当前信息。