FastAPI + MCP 实战解析——从“没有 MCP 的混乱接入”到“工程级 AI 能力治理”

一、MCP 出现之前：AI 接入后端的“野蛮生长阶段”

1.1 最早期的做法：Prompt + 后端兜底

很多团队最初的 AI 接入方式大致如下：

Prompt：
你是一个后端助手。
数据库表结构如下：
order(id, user_id, status, pay_status, ...)
请根据用户问题生成 SQL 查询。

然后在后端：

1. 把模型返回的 SQL 拿出来
2. 简单校验
3. 直接执行
4. 把结果再丢回给模型总结

1.2 这种模式在工程上会迅速失控

本质问题只有一句话：AI 被当成“人”，却拥有了“系统级权限”。

二、MCP 是为了解决什么问题而出现的？

2.1 MCP 的核心定位（先说人话）

在技术领域中，MCP（Model Context Protocol）有着其独特的定义和范畴，MCP（Model Context Protocol）并不是：

• 它并非是对象关系映射ORM。ORM主要是用于实现面向对象编程语言里不同类型系统的数据之间的转换，是一种为了解决面向对象与关系数据库存在的互不匹配现象的技术。而MCP有着与ORM截然不同的功能和应用场景，它并不承担将对象模型映射到关系数据库的任务。
• MCP也不是远程过程调用RPC。RPC允许程序调用另一个地址空间（通常是共享网络的另一台机器上）的过程或函数，就像调用本地的过程一样。但MCP并不具备RPC那种跨网络调用远程服务的特性，它有着自己独立的工作模式和目标。
• 同时，MCP也不是软件开发工具包SDK。SDK通常是一系列软件开发工具的集合，包含了文档、示例代码、调试工具等，用于帮助开发者更方便地进行软件的开发。然而，MCP并不属于这类提供开发工具和资源的范畴，它有着自身独特的用途和价值。
• 最后，MCP不是代理框架Agent 框架。Agent 框架一般是用于构建智能代理系统，这些代理可以自主地完成特定的任务。而MCP并不具备Agent 框架那样的智能代理功能，它有着与Agent 框架不同的设计理念和应用方向。

MCP真正解决的是：

👉 “AI 如何在不直接操作系统的前提下，安全地使用系统能力”

一句话总结：

让 AI 看得见能力，但摸不着系统。

2.2 MCP 的关键思想：Tool 而不是 Prompt

三、FastApiMCP 是什么？解决了什么落地问题？

3.1 FastApiMCP 的角色

FastApiMCP 是 MCP 协议在 FastAPI 生态中的工程化实现。

你可以直接使用：

from fastapi_mcp import FastApiMCP

它做了三件关键的事情：

1. 把 FastAPI 接口声明为 MCP Tool
2. 自动生成 Tool Schema（给模型看的能力说明）
3. 把模型的 Tool 调用，转化为真实的 FastAPI 请求

3.2 MCP 中几个关键名词解释（工程向）

• MCP Tool

MCP Tool 是专门为模型调用而精心设计的“能力单元”，它与普通的 API 有着本质的区别。普通 API 通常具有更广泛的通用性和灵活性，适用于各种不同的应用场景和需求。而 MCP Tool 则是针对特定的模型调用任务进行定制化开发的，它专注于为模型提供特定的功能和服务，以满足模型在运行过程中的各种需求。

👉 MCP Tool 具有参数固定、行为明确、职责单一的显著特点。参数固定意味着在使用 MCP Tool 时，其输入参数是预先设定好的，不会随意变动，这样可以确保模型在调用时能够准确地传递所需的信息。行为明确表示 MCP Tool 在接收到输入参数后，会按照既定的规则和逻辑进行处理，并输出确定的结果，不会出现模糊或不确定的行为。职责单一则强调 MCP Tool 只负责完成一项特定的任务，不会承担过多的额外功能，从而保证了其功能的专业性和高效性。

• MCP Server

MCP Server 是用于暴露 Tool 的服务端，在这个特定的环境中，这里所指的就是 FastAPI。FastAPI 是一个基于 Python 的现代、快速（高性能）的 Web 框架，它具有许多优秀的特性，如快速开发、易于使用、高性能等。MCP Server 通过 FastAPI 来提供服务，将 MCP Tool 所具备的各种能力以一种规范、有序的方式暴露给外部，使得其他系统或模型能够方便地调用这些工具。它就像是一个桥梁，连接着 MCP Tool 和需要使用这些工具的模型或系统，确保数据的准确传输和交互。

• MCP Client

MCP Client 是大模型运行的重要环境，其主要功能是用来发现和调用 Tool。在一个复杂的系统中，存在着众多的 MCP Tool，MCP Client 就像是一个智能的“探索者”，它能够在众多的工具中准确地找到模型所需的特定 Tool。当模型需要执行某项任务时，MCP Client 会根据任务的需求，在其可访问的范围内搜索合适的 Tool，并将模型的调用请求准确地传递给相应的 Tool。同时，MCP Client 还负责处理调用过程中的各种交互和数据传输，确保模型能够顺利地使用 Tool 来完成任务。

• Tool Schema

Tool Schema 是专门为模型设计的“能力说明书”，它与我们通常所看到的给人看的文档有着明显的区别。给人看的文档通常会采用自然语言进行详细的描述，包含丰富的解释、示例和说明，以方便人类用户理解和使用。而 Tool Schema 则是一种更具结构化和标准化的信息表示方式，它主要是为了让模型能够理解 Tool 的功能、输入输出要求等关键信息。Tool Schema 以一种模型能够识别和处理的格式来描述 Tool 的各种属性和使用规则，使得模型在调用 Tool 时能够准确地了解其能力范围和使用方法，从而实现高效、准确的调用。

四、FastApiMCP 在 FastAPI 中如何使用（完整示例）

4.1 初始化 FastApiMCP

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()
mcp = FastApiMCP(app)

此时你的 FastAPI 应用已经具备 MCP Server 能力。

4.2 定义一个 MCP Tool（订单查询示例）

业务目标

让 AI 只读查询 单个订单状态，用于问题排查。

from pydantic import BaseModel

class OrderQueryInput(BaseModel):
    order_id: str

class OrderQueryOutput(BaseModel):
    order_id: str
    status: str
    pay_status: str
    delivery_status: str

@mcp.tool()
def query_order_status(input: OrderQueryInput) -> OrderQueryOutput:
    order = get_order_from_db(input.order_id)

    return OrderQueryOutput(
        order_id=order.id,
        status=order.status,
        pay_status=order.pay_status,
        delivery_status=order.delivery_status
    )

4.3 这里发生了什么（非常关键）

• 在实际的应用场景当中，AI 不能传 SQL。这意味着在数据交互和处理的过程里，AI 并不具备直接传递 SQL 语句的能力。SQL 作为一种专门用于管理和操作数据库的语言，在数据查询、插入、更新和删除等操作中起着关键作用。然而，由于安全、兼容性等多方面的考量，AI 无法将 SQL 语句直接进行传递，从而避免可能出现的 SQL 注入等安全隐患以及因不同数据库对 SQL 语法支持差异而导致的兼容性问题。
• 同样地，AI 不能拼条件。在构建数据查询时，常常需要根据不同的需求拼接各种查询条件，以此来精确筛选出所需的数据。但 AI 并不具备自动拼接这些条件的功能。这是因为条件拼接需要对业务逻辑有深入的理解，并且要考虑到数据的完整性、准确性和有效性。如果 AI 随意拼接条件，可能会导致查询结果不准确或者出现错误，进而影响整个系统的正常运行。
• 值得注意的是，AI 只能传 order_id。也就是说，在与其他系统或模块进行数据交互时，AI 所能传递的信息比较有限，仅仅局限于 order_id 这一特定的数据项。order_id 通常是订单的唯一标识符，在订单管理、物流跟踪等业务流程中具有重要的作用。AI 只能传递这一特定的数据，这就要求系统在设计和开发时，要充分考虑如何利用这一有限的信息来实现各种业务功能。
• 最后，数据查询逻辑完全在你控制的后端代码中。这表明数据查询的具体实现和控制都由开发者所编写的后端代码来完成。后端代码可以根据业务需求灵活地设计和实现数据查询的逻辑，包括如何连接数据库、如何构建查询语句、如何处理查询结果等。这样的设计使得开发者能够对数据查询过程进行全面的掌控，确保数据的安全性、准确性和高效性，同时也便于对系统进行维护和扩展。

五、项目级对比：没有 MCP vs 使用 FastApiMCP

5.1 没有 MCP 的典型项目结构

ai_prompt/
  ├── order_prompt.txt
  ├── sql_rules.md

service/
  ├── ai_router.py   # 解析模型输出
  ├── sql_executor.py

问题：

• Prompt 成为核心逻辑
• 后端只是“执行器”
• 无法治理

5.2 使用 FastApiMCP 后的结构

app/
  ├── mcp/
  │    ├── order_tools.py
  │    └── user_tools.py
  ├── services/
  │    └── order_service.py

优势：

• 能力显式
• 行为可控
• 责任清晰

六、MCP 为开发者带来的实际价值

6.1 安全性提升（不是“更安全一点”，而是范式变化）

6.2 可维护性与可演进性

• 在软件开发和编程的领域中，Tool（工具）本质上是代码。代码作为程序的核心组成部分，是程序员们使用特定的编程语言编写出来的一系列指令集合。这些指令经过编译或者解释后，能够实现各种特定的功能，而这里所说的Tool就是通过代码来实现其工具性的作用。它可以是一个简单的脚本，用于完成数据的处理和转换；也可以是一个复杂的软件系统，涵盖了多个模块和功能，帮助开发者更高效地完成特定的任务，比如自动化测试、代码优化等。
• 在系统架构和数据交互的场景下，Schema（模式）是契约。Schema就像是一种规范和约定，它定义了数据的结构、格式以及各个元素之间的关系。在不同的系统或者模块之间进行数据交换时，Schema起到了至关重要的作用。它确保了数据的一致性和准确性，就如同一份具有法律效力的契约一样，规定了双方在数据交互过程中必须遵循的规则。无论是数据库中的表结构定义，还是API接口的数据格式规范，Schema都明确了数据的组织方式和使用规则，使得不同的组件能够按照统一的标准进行协作和通信。
• 在现代的开发理念和设计模式中，Prompt（提示）不再承载业务规则。Prompt通常是用于引导用户输入或者与系统进行交互的提示信息，它的主要作用是提供友好的用户界面和交互体验。而业务规则是关于业务流程、业务逻辑和业务约束的一系列规定，这些规则应该由专门的业务逻辑层或者规则引擎来处理。将业务规则从Prompt中分离出来，能够使代码的结构更加清晰，提高代码的可维护性和可扩展性。这样，Prompt就可以专注于提供简洁明了的提示信息，而业务规则则可以独立地进行管理和修改，避免了两者之间的耦合带来的复杂性和潜在的错误。

6.3 AI 能力可以“规模化治理”

你可以：

• 在实际的应用场景当中，为了实现更加精准和高效的功能运用，我们需要给不同模型暴露不同 Tool。不同的模型往往具有各自独特的特性和应用范围，有的模型可能擅长于数据处理，有的模型则在图像识别方面表现突出。针对这些具有不同专长的模型，我们应该有针对性地为其提供合适的 Tool。例如，对于专注于数据处理的模型，我们可以为其暴露数据清洗、数据分析等相关的 Tool，这样能够让模型充分发挥自身优势，更加高效地完成数据处理任务。而对于图像识别模型，我们则可以为其提供图像增强、特征提取等 Tool，以提升模型在图像识别方面的性能。通过给不同模型暴露不同 Tool，能够让各个模型在其擅长的领域充分发挥作用，从而提高整个系统的运行效率和处理能力。
• 在不同的环境下，系统所面临的需求和挑战也各不相同。因此，我们需要给不同环境暴露不同能力。不同的环境包括开发环境、测试环境和生产环境等。在开发环境中，开发者可能更需要系统具备强大的调试和开发辅助能力，例如代码调试工具、实时反馈机制等，这样能够帮助开发者快速定位和解决问题，提高开发效率。在测试环境中，系统需要具备全面的测试能力，如性能测试、兼容性测试等，以确保系统在上线前能够稳定运行。而在生产环境中，系统则需要重点关注稳定性和安全性，需要具备故障预警、数据加密等能力，以保障系统的正常运行和数据的安全。通过根据不同环境的特点和需求，为其暴露不同的能力，能够让系统在各种环境下都能更好地适应和发挥作用。
• 在实际的使用过程中，对 Tool 调用做审计和限流是非常必要的。Tool 的调用情况反映了系统的运行状态和用户的使用行为。对 Tool 调用进行审计，可以详细记录每个 Tool 的调用时间、调用频率、调用者等信息。通过对这些审计信息的分析，我们可以了解系统的使用情况，发现潜在的问题和风险。例如，如果某个 Tool 的调用频率异常高，可能意味着存在程序漏洞或者用户滥用的情况，需要及时进行排查和处理。同时，对 Tool 调用进行限流也是保障系统稳定运行的重要措施。当大量用户同时请求调用某个 Tool 时，如果不进行限流，可能会导致系统资源耗尽，影响系统的正常运行。通过设置合理的限流策略，如限制每个用户在一定时间内的调用次数、限制并发调用数量等，可以有效地控制 Tool 的调用流量，确保系统在高并发情况下仍能稳定运行。

七、MCP 的使用复杂性与边界

7.1 MCP 不是“零成本”

7.2 什么情况下不适合 MCP？

• 纯文本生成
• 非结构化内容创作
• 一次性 Demo

八、MCP 能扩展到什么程度？

在工程实践当中，MCP 具备一定的扩展性，你可以将其扩展至以下几个方面：

• 多 Tool 协作：通过实现多个不同工具之间的协同合作，充分发挥各个工具的优势，让它们相互配合、相互补充，从而提升整体的工作效率和效果，实现更为复杂和多样化的任务处理。
• 多系统只读分析：针对多个不同的系统进行只读分析，在不改变系统原有数据和状态的前提下，深入挖掘各个系统中的数据信息，获取有价值的洞察，为后续的决策提供有力的支持。
• 排障 Agent：借助排障 Agent 自动地对系统中出现的故障问题进行检测、诊断和排除，能够快速定位故障根源，及时采取有效的解决措施，减少故障对系统正常运行的影响，提高系统的稳定性和可靠性。
• 质量分析 Agent：利用质量分析 Agent 对系统的各项质量指标进行全面、深入的分析，评估系统的质量状况，找出潜在的质量问题和风险，为系统的优化和改进提供方向和依据。

然而，需要特别注意的是，有一些扩展方向不建议进行尝试：

• 自动写库：自动写库可能会导致数据的混乱和错误，破坏数据的完整性和一致性，同时也可能会引发安全风险，因此不建议轻易采用这种扩展方式。
• 自动执行危险操作：自动执行危险操作存在极大的安全隐患，可能会对系统造成严重的损害，甚至导致系统崩溃，所以不应该让 MCP 自动执行这类操作。
• 绕过人工审批：绕过人工审批流程可能会导致决策的不严谨和不合理，无法对操作的风险和影响进行有效的评估和控制，容易引发一系列的问题，因此不建议这么做。