MCP时代API设计演进：从Swagger到Agent

最初发表于 tamiz.pro。

在多云平台（MCP）日益普及以及 AI 智能体能力不断增强的推动下，API 开发格局正在经历一场剧变。过去，Swagger（现为 OpenAPI Specification）等工具彻底改变了我们设计、描述和使用 API 的方式，提供了一种标准化且人类与机器均可读取的格式。然而，MCP 时代以分布式服务、动态环境和自主 AI 使用方为特征，它所提出的需求要求我们重新审视这些基础方法。本文将深入探讨如何重新构想 API 的设计、安全与文档，以应对这些新挑战，并从静态规范迈向动态且能够感知智能体的范式。

1. API 范式的演进

2. 多云平台（MCP）与 API 复杂性

3. AI 智能体成为一等 API 使用方

4. 面向智能体中心化系统重新构想 API 设计 4.1. 语义 API 与本体 4.2. 事件驱动架构（EDA）与异步 API 4.3. 用于智能体发现的 GraphQL 与超媒体 API

4.1. 语义 API 与本体

4.2. 事件驱动架构（EDA）与异步 API

4.3. 用于智能体发现的 GraphQL 与超媒体 API

5. MCP 与智能体时代的高级 API 安全 5.1. 零信任与微分段 5.2. AI 驱动的威胁检测与行为分析 5.3. 去中心化身份与可验证凭证 5.4. 策略即代码与自动化治理

5.1. 零信任与微分段

5.2. AI 驱动的威胁检测与行为分析

5.3. 去中心化身份与可验证凭证

5.4. 策略即代码与自动化治理

6. 面向 AI 与人类的动态 API 文档 6.1. 可执行规范与活文档 6.2. AI 生成的文档与自然语言界面 6.3. 作为可观测性中枢的 API 网关

6.1. 可执行规范与活文档

6.2. AI 生成的文档与自然语言界面

6.3. 作为可观测性中枢的 API 网关

7. 服务网格在 MCP 时代的作用

8. 实际影响与未来展望

9. 常见问题

10. API 范式的演进

API 已从简单的 RPC（Remote Procedure Call，远程过程调用）机制演进为 RESTful 范式，后者将无状态、面向资源以及标准 HTTP 方法推到了核心位置。Swagger/OpenAPI 随之成为推动 REST 发展的关键工具，它提供了一种描述 API 能力、请求/响应结构和身份验证机制的通用语言。这一规范极大改善了开发者体验，支持自动生成客户端 SDK、交互式文档以及基本验证。然而，整个行业正在超越静态、以人类为中心的使用方式。

微服务和云原生架构的出现，使 API 的数量与复杂性提升到了新的层次。如今，多云战略以及复杂 AI 智能体作为主要 API 使用方的兴起，正在进一步拓展边界，要求 API 生态系统具备更强的动态性、上下文感知能力和智能化水平。

2. 多云平台（MCP）与 API 复杂性

多云平台（MCP）是一种战略：组织利用多个云提供商（例如 AWS、Azure、GCP、Alibaba Cloud）的服务，在成本、性能、韧性或避免供应商锁定等方面实现优化。尽管 MCP 能够带来显著收益，但也为 API 管理引入了诸多挑战：

分布式身份与访问管理：确保跨不同云提供商和本地环境的身份验证与授权保持一致，是一项极其艰巨的任务。身份联合与集中式策略执行因而变得至关重要。

网络延迟与数据引力：API 跨不同云调用服务时，可能产生显著的延迟和出口流量成本。智能路由、缓存和数据本地化策略必不可少。

可观测性与监控：要跨碎片化基础设施获得 API 性能、错误和安全状况的统一视图，需要高级的分布式追踪与聚合工具。

合规与治理：跨多个司法管辖区和云提供商遵守监管要求（GDPR、HIPAA 等），会为 API 设计和数据处理增加多层复杂性。

API 网关蔓延：每个云提供商都有自己的 API Gateway（例如 AWS API Gateway、Azure API Management）。如何在这些网关之间一致地管理 API，或者如何通过统一控制平面对它们进行抽象，是一项关键的架构挑战。

传统 Swagger 文件主要描述单个 API 端点。在 MCP 环境中，跨云 API 的编排、调用方的上下文（人类还是智能体、内部还是外部）以及服务的动态可用性，都变得至关重要。

3. AI 智能体成为一等 API 使用方

或许最具变革性的转变，是 AI 智能体的崛起。它们是自主的软件实体，通常由大语言模型（LLM）驱动，能够理解自然语言指令、进行推理和规划，并通过与外部工具及 API 交互来执行操作。对于 AI 智能体而言，API 不只是数据端点，更是实现目标的工具。这改变了一切：

API 发现与理解：智能体需要在没有人工干预的情况下发现相关 API，并理解其能力、参数和预期输出。静态 Swagger 文件虽然可由机器读取，但通常缺乏 AI 实现可靠自主发现和面向目标使用所需的语义丰富性。

动态调用：智能体必须能够动态构造 API 调用、处理响应，并根据上下文或失败情况调整调用策略。

错误处理与恢复：智能体需要复杂的机制来理解 API 错误、区分暂时性问题与永久性问题，并实施恢复策略（重试、回退或替代操作）。

安全上下文：智能体的访问权限和信任级别可能与人类用户存在显著差异。根据智能体的意图和身份进行细粒度授权至关重要。

持续学习：智能体可以从 API 交互中学习，优化其使用模式，甚至为 API 本身提出改进建议。

这种范式转变要求 API 不仅得到描述，还必须能够被智能系统理解和操作。

4. 面向智能体中心化系统重新构想 API 设计

为 AI 智能体设计 API 并不只是提供 CRUD 操作，还需要重点关注语义、可发现性和动态适应能力。

4.1. 语义 API 与本体

要实现真正的 AI 智能体自主性，API 需要嵌入更多语义信息。这包括：

丰富的元数据：除基本数据类型外，API 还应公开有关参数含义、操作目的以及资源之间关系的元数据。可以利用 JSON-LD、RDF 和 schema.org 等技术，直接在 API 响应中或 OpenAPI 规范旁嵌入语义注解。

本体与知识图谱：为领域定义正式本体，并将 API 端点映射到这些本体概念，使智能体能够在更高抽象层次上推理 API 的能力。由可用服务及其相互依赖关系构成的知识图谱，可以成为智能体强大的发现机制。

以一个处理客户订单的 API 为例。语义 API 不会只声明 productId: string，而可能指定 productId: URI，令其指向产品目录本体；操作 processOrder 也可能关联到 fulfillment:OrderProcessing 概念。这能让智能体获得丰富得多的理解。

4.2. 事件驱动架构（EDA）与异步 API

AI 智能体经常运行在无法或不宜立即获得同步响应的环境中。因此，使用异步 API 的事件驱动架构变得愈发重要：

Webhook 与 Server-Sent Events（SSE）：智能体可以订阅事件（例如 order_status_changed、data_feed_updated），而不必持续轮询。这可以减少资源消耗并支持实时响应。

消息队列与代理（Kafka、RabbitMQ）：对于高吞吐量、解耦的通信，智能体可以向消息队列发布命令或从中消费事件。这能够提供韧性和可扩展性，尤其适用于服务可能位于不同云区域的 MCP 场景。

AsyncAPI Specification 正逐渐成为事件驱动系统中与 OpenAPI 对应的规范，它支持对消息格式、通道和协议进行正式描述。智能体可以使用这些规范订阅相关事件并自主响应。

4.3. 用于智能体发现的 GraphQL 与超媒体 API

尽管 OpenAPI 擅长描述 REST 端点，但 GraphQL 与超媒体 API 在智能体驱动的发现和交互方面具有不同的优势：

GraphQL: AI 智能体可以精确地请求它们需要的数据，减少过度提取和不足提取的问题。更重要的是，GraphQL 的内省功能允许智能体动态发现 schema 和可用的查询/变更，能够即时调整数据检索策略。

Hypermedia (HATEOAS): 使用 HATEOAS 原则设计的 API 在响应中直接嵌入指向相关资源和操作的链接。这允许智能体在不需要预先了解所有可能 URL 的情况下浏览 API 状态空间，模仿人类浏览网站的方式。智能体可以通过解析返回的链接来发现后续操作，比如"下一页"或"批准订单"链接。

{
  "orderId": "12345",
  "status": "pending_approval",
  "_links": [
    { "rel": "approve", "href": "/orders/12345/approve", "method": "POST" },
    { "rel": "reject", "href": "/orders/12345/reject", "method": "POST" },
    { "rel": "customer", "href": "/customers/ABCDEF" }
  ]
}

在这个 HATEOAS 例子中，理解 rel（关系）的智能体可以动态决定批准或拒绝订单，或获取客户详情，无需硬编码这些路径。

5. MCP 和智能体时代的高级 API 安全

在 MCP 环境中保护 API，尤其是涉及 AI 智能体时，需要采用多层、自适应的方法，远超传统 API 密钥或 OAuth2。

5.1. 零信任和微分段

在零信任模型中，无论是人类还是 AI 智能体，任何用户或服务都不被默认信任，即使它们在网络周界内。每个请求都必须进行身份验证、授权和持续验证。

相互 TLS (mTLS)：确保客户端（智能体）和服务器相互身份验证，建立安全的加密通道。

细粒度授权 (ABAC/PBAC)：基于属性的访问控制 (ABAC) 或基于策略的访问控制 (PBAC) 允许基于用户/智能体、资源、环境和操作的属性做出高度细粒度的授权决策。这对权限可能非常具体且动态的智能体至关重要。

微分段：将 API 服务及其依赖隔离到小的、安全的网络段中，限制了违规的影响范围，在不同云提供商网络之间尤其重要。

5.2. AI 驱动的威胁检测和行为分析

传统的 WAF（Web 应用防火墙）和 API 网关通常依赖于基于签名的检测。MCP 和智能体时代需要更智能的安全方案：

异常检测：AI/ML 模型可以为人类和智能体使用者建立正常 API 流量模式的基线（请求速率、负载大小、地理来源、访问时间）。偏差会触发警报或自动阻止。

机器人和智能体行为分析：区分合法 AI 智能体流量和恶意机器人活动需要分析行为模式，如请求序列、速度和资源访问模式。这可以检测 API 滥用、数据抓取或凭证填充等复杂攻击。

上下文风险评分：根据源 IP 声誉、用户/智能体身份、访问历史和负载内容等因素，为每个 API 请求分配动态风险分数。更高的风险分数可以触发更强的身份验证挑战或阻止请求。

5.3. 去中心化身份和可验证凭证

跨多个云和众多 AI 智能体管理身份可能会很复杂。去中心化身份 (DID) 和可验证凭证 (VC) 提供了一个有前景的解决方案：

自主身份：智能体可以拥有它们控制的 DID，允许它们呈现可验证的凭证（例如，"授权读取财务记录"或"认证的 LLM 提供商"）。这将范式从单一的 API 密钥转变为细粒度、密码学可验证的权限，可以按需呈现。

对于支持 MCP 的 API 网关，身份验证流程演进如下：

握手：客户端智能体呈现其 DID 和包含其 VC 的签名 JWT。

验证：服务器针对相关签发者的 DID 文档验证 VC 签名。

授权：策略引擎（如 OPA）根据被访问的特定 MCP 工具或资源评估 VC 中的声明。

3. 文档转变：从静态规范到动态交互

Swagger/OpenAPI 是 API 能力的静态快照。在 MCP 时代，文档必须是动态的，反映智能体交互的有状态上下文。我们正在朝向交互式文档发展，其中规范本身可以被智能体查询、执行和验证。

与其将 YAML 文件放在仓库中，MCP 启用的 API 暴露一个"清单"端点。这个 JSON-LD 文档描述：

工具定义：输入 schema、输出 schema 和副作用描述。

资源模板：数据检索的 URI 模式。

提示模板：用于 LLM 交互的可重用指令集。

能力标志：流式传输、取消或批处理等功能的布尔指示器。

考虑这个简化的 MCP 清单片段：

{
  "mcp_version": "1.0.0",
  "name": "Financial Data Service",
  "tools": [
    {
      "name": "get_balance",
      "description": "Retrieve the current balance for a verified account.",
      "input_schema": {
        "type": "object",
        "properties": {
          "account_id": { "type": "string", "description": "The unique account identifier" },
          "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] }
        },
        "required": ["account_id"]
      },
      "security_schemes": ["BearerAuth"],
      "privacy_level": "PII_RESTRICTED"
    }
  ]
}

开发者不再仅依赖 Postman 集合。他们使用 MCP 兼容的客户端来编程地测试端点。智能体可以自动发现可用工具，推断所需参数，并对沙盒环境执行测试调用，为 schema 更改或破坏性更新提供即时反馈。

4. 智能体流程时代的安全性

安全模型从保护端点转变为保护意图。由于智能体可以链接多个 API 调用，一个步骤中的漏洞可能会危害整个工作流。

提示注入：攻击者将恶意指令注入智能体读取的资源（例如博客文章）。智能体然后可能基于注入的文本执行危险的工具调用。缓解：实现意图验证层。在执行工具之前，API 网关或辅助服务使用轻量级 LLM 针对安全策略分析智能体的提议操作。

工具滥用：智能体获得低权限工具的访问权，但使用它来提升权限或通过侧信道泄露数据。缓解：按设计的最小权限。MCP 工具应该范围很小。使用在特定工具调用之后立即过期的临时令牌。

这是一个概念性 Python 示例，显示一个拦截 MCP 工具调用的安全辅助服务：

import asyncio
from typing import Dict, Any

class SafetySidecar:
    def __init__(self, llm_client):
        self.llm = llm_client

async def validate_tool_call(self, tool_name: str, args: Dict[str, Any]) -> bool:
        """
        Intercepts tool calls and validates them against safety policies.
        """
        prompt = f"""
        Analyze the following tool call for safety violations.
        Tool: {tool_name}
        Arguments: {args}

Policy: 
        - No PII should be passed to external logging tools.
        - No financial transactions should exceed $1000 without approval.
        - No system-level commands are allowed.

Return ONLY 'ALLOW' or 'DENY'.
        """

response = await self.llm.generate(prompt)
        return "ALLOW" in response.content

async def main():
    sidecar = SafetySidecar(llm_client=OpenAIClient())

# Simulate an MCP tool call
    tool_name = "send_email"
    args = {
        "to": "user@example.com",
        "body": "Hello, here is your sensitive SSN: 123-45-6789"
    }

is_safe = await sidecar.validate_tool_call(tool_name, args)

if is_safe:
        print("Tool call executed.")
    else:
        print("Tool call blocked by Safety Sidecar.")

if __name__ == "__main__":
    asyncio.run(main())

5. 构建您的第一个 MCP 就绪的 API

让我们使用 FastAPI 构建一个简单的 Python API，暴露一个 MCP 兼容的接口。

创建 mcp_manifest.json：

{
  "mcp_version": "1.0.0",
  "name": "Todo Agent API",
  "tools": [
    {
      "name": "add_todo",
      "description": "Add a new task to the todo list.",
      "input_schema": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "priority": { "type": "integer", "minimum": 1, "maximum": 5 }
        },
        "required": ["title"]
      }
    }
  ]
}

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional
import json

app = FastAPI()

# In-memory store for demonstration
todos = []

class TodoInput(BaseModel):
    title: str
    priority: Optional[int] = 1

@app.get("/mcp/manifest")
async def get_manifest():
    """Expose the MCP manifest for agent discovery."""
    with open("mcp_manifest.json", "r") as f:
        return json.load(f)

@app.post("/tools/add_todo")
async def add_todo(item: TodoInput):
    """
    The actual implementation of the MCP tool.
    Note: The endpoint name matches the tool name in the manifest.
    """
    todo = {"title": item.title, "priority": item.priority, "id": len(todos) + 1}
    todos.append(todo)
    return {"status": "success", "todo": todo}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

现在你可以使用任何 MCP 兼容的 AI 智能体框架（如 LangChain 的 MCP 集成或 Microsoft 的 AutoGen）来发现和使用这个 API。AI 智能体将：

• 识别 add_todo 为可用工具。

• 构造指向 /tools/add_todo 的 JSON-RPC 请求，包含所需参数。

• 处理响应并将其集成到自己的工作流中。

结论：未来是智能体驱动的

从 Swagger 到 MCP 的转变不仅仅是技术升级，更是一场哲学上的转变，影响了我们如何设计软件。我们正在从人机接口（其中人类将意图转化为精确的 API 调用）转向机器对机器接口，AI 智能体可以自主协商、验证和执行复杂的工作流。

架构师和开发者的关键要点：

为可发现性而设计：你的 API 应该用 AI 智能体可以轻松消费的机器可读格式来描述自己。

拥抱细粒度安全：用可验证的凭证和上下文感知授权替代静态密钥。

优先考虑安全：实施能够推理工具调用意图而非仅其语法的护栏。

与 AI 智能体迭代：使用 AI 智能体来测试你的 API。如果 AI 智能体无法轻松理解和使用你的 API，你的客户也不会。

静态 API 文档的时代正在结束。充满生命力、随时准备好的、可供 AI 智能体使用的 API 时代已经开始。从今天开始为这个未来构建，你的系统将为明天的自主应用做好准备。

如需进一步行动，你可以考虑屏蔽此人和/或举报滥用