13.4 · MCP 协议参考（MCP Protocol Reference）

MCP 协议参考（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/13.4-mcp-protocol-reference

翻译时间：2026-05-27T08:45:19.688Z

翻译模型：deepseek-chat

原文字符数：11091

项目：Cognee (cognee)

---

MCP 协议参考

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• .github/workflows/dockerhub-mcp.yml
• Dockerfile
• cognee-mcp/Dockerfile
• cognee-mcp/README.md
• cognee-mcp/entrypoint.sh
• cognee-mcp/pyproject.toml
• cognee-mcp/src/__init__.py
• cognee-mcp/src/client.py
• cognee-mcp/src/cognee_client.py
• cognee-mcp/src/server.py
• cognee-mcp/uv.lock
• cognee/alembic/versions/7c5d4e2f8a91_add_parent_user_id_to_users.py
• cognee/modules/users/authentication/default/default_transport.py
• cognee/modules/users/authentication/get_api_auth_backend.py
• cognee/modules/users/authentication/get_client_auth_backend.py
• cognee/tests/unit/test_add_parent_user_id_migration.py
• docker-compose.yml
• entrypoint.sh

本文档提供了 Cognee 的模型上下文协议（MCP）服务器实现的技术参考。内容涵盖协议架构、传输模式、工具接口、消息格式以及配置选项。

协议架构总览

Cognee 使用 FastMCP 框架实现了模型上下文协议（MCP）规范 cognee-mcp/src/server.py:73。该服务器充当 MCP 客户端（如 Claude Desktop、Cursor、Cline 等 AI 助手）与 Cognee 知识引擎之间的桥梁，将认知操作暴露为 MCP 工具。

该实现支持两种操作模式，定义在 CogneeClient 抽象层中：

• 直接模式：服务器直接导入并使用本地 cognee 包执行 Cognee 函数 cognee-mcp/src/cognee_client.py:64-68。
• API 模式：服务器使用 httpx.AsyncClient 将请求代理到运行中的 Cognee REST API 服务器 cognee-mcp/src/cognee_client.py:58-62。

核心 MCP 组件

标题：MCP 协议架构与数据流

graph TB
    subgraph "MCP_客户端层"
        ClaudeDesktop["Claude Desktop"]
        Cursor["Cursor IDE"]
        Cline["Cline"]
    end

    subgraph "传输层"
        StdioTransport["stdio 传输<br/>基于管道的进程间通信"]
        SSETransport["SSE 传输<br/>HTTP 服务器推送事件<br/>端口 8000"]
        HTTPTransport["可流式 HTTP 传输<br/>POST /mcp 端点<br/>端口 8000"]
    end

    subgraph "FastMCP 服务器"
        MCPInstance["FastMCP('Cognee')<br/>mcp = FastMCP('Cognee')"]

        subgraph "工具注册表"
            CognifyTool["@mcp.tool()<br/>cognify()"]
            SearchTool["@mcp.tool()<br/>search()"]
            RememberTool["@mcp.tool()<br/>remember()"]
            RecallTool["@mcp.tool()<br/>recall()"]
            ForgetTool["@mcp.tool()<br/>forget()"]
            StatusTool["@mcp.tool()<br/>cognify_status()"]
        end

        subgraph "自定义路由"
            HealthRoute["@mcp.custom_route('/health')<br/>health_check()"]
        end
    end

    subgraph "后端抽象层"
        CogneeClientEntity["CogneeClient<br/>cognee_client"]

        DirectMode["直接模式<br/>import cognee<br/>self.cognee"]
        APIMode["API 模式<br/>httpx.AsyncClient<br/>self.client"]
    end

    subgraph "Cognee 后端"
        FastAPIServer["FastAPI REST API<br/>cognee.api.client:app"]
        CogneeCore["Cognee 核心函数<br/>add/cognify/search"]
    end

    ClaudeDesktop --> StdioTransport
    Cursor --> SSETransport
    Cline --> HTTPTransport

    StdioTransport --> MCPInstance
    SSETransport --> MCPInstance
    HTTPTransport --> MCPInstance

    MCPInstance --> CognifyTool
    MCPInstance --> SearchTool
    MCPInstance --> RememberTool
    MCPInstance --> RecallTool
    MCPInstance --> ForgetTool
    MCPInstance --> StatusTool
    MCPInstance --> HealthRoute

    CognifyTool --> CogneeClientEntity
    SearchTool --> CogneeClientEntity
    RememberTool --> CogneeClientEntity
    RecallTool --> CogneeClientEntity
    ForgetTool --> CogneeClientEntity
    StatusTool --> CogneeClientEntity

    CogneeClientEntity --> DirectMode
    CogneeClientEntity --> APIMode

    DirectMode --> CogneeCore
    APIMode --> FastAPIServer
    FastAPIServer --> CogneeCore

来源：cognee-mcp/src/server.py:73-77、cognee-mcp/src/cognee_client.py:31-68、Dockerfile:48-54

传输协议

MCP 服务器支持三种传输模式，通过 --transport 参数或 TRANSPORT_MODE 环境变量选择 cognee-mcp/entrypoint.sh:45-46。

传输模式对比

传输模式	使用场景	默认端口	协议	连接模型
stdio	本地 CLI 工具、IDE	无	标准输入/输出	双向管道
sse	Web 客户端、实时通信	8000	HTTP GET + SSE	长连接 HTTP
http	Web 部署	8000	HTTP POST	请求-响应

stdio 传输

标准输入/输出传输是默认模式 cognee-mcp/entrypoint.sh:45。它使用标准管道进行通信，推荐用于本地 IDE 集成，如 Claude Desktop。

SSE 传输

服务器推送事件传输用于实时更新。服务器使用 CORSMiddleware 允许 Web 客户端访问 cognee-mcp/src/server.py:168-175。

服务器初始化：

# cognee-mcp/src/server.py:166-184
async def run_sse_with_cors():
    sse_app = mcp.sse_app()
    sse_app.add_middleware(
        CORSMiddleware,
        allow_origins=_get_cors_origins(),
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )
    ...
    server = uvicorn.Server(config)
    await server.serve()

HTTP 可流式传输

基于 HTTP POST 的无状态请求-响应通信，使用 streamable_http_app() cognee-mcp/src/server.py:189。

来源：cognee-mcp/src/server.py:166-203、cognee-mcp/entrypoint.sh:44-57

MCP 工具接口规范

工具通过 @mcp.tool() 装饰器注册，该装饰器会生成符合 MCP 规范的 JSON 模式 cognee-mcp/src/server.py:18-19。

remember 工具

暴露一个简化的 API 用于存储记忆。它抽象了添加数据和触发认知处理的过程 cognee-mcp/src/server.py:257-263。

工具签名：

# cognee-mcp/src/server.py:257-263
@mcp.tool(name="remember", description="将信息存储到永久记忆中")
async def remember(
    data: str,
    dataset_name: str = "main_dataset",
    is_session_memory: bool = False,
) -> list[types.TextContent]:

召回工具

提供一个统一的接口用于检索存储的知识 cognee-mcp/src/server.py:469-474。

工具签名：

# cognee-mcp/src/server.py:469-474
@mcp.tool(name="recall", description="在记忆中搜索信息")
async def recall(
    query: str,
    search_type: str = "GRAPH_COMPLETION",
    top_k: int = 10,
) -> list[types.TextContent]:

支持的搜索类型： GRAPH_COMPLETION、RAG_COMPLETION、CODE、CHUNKS、SUMMARIES、CYPHER、FEELING_LUCKY cognee-mcp/src/server.py:483-492。

cognify_status 工具

允许客户端监控后台处理任务的进度 cognee-mcp/src/server.py:318-322。

来源：cognee-mcp/src/server.py:257-316、cognee-mcp/src/server.py:469-540

后端抽象层

CogneeClient 类为本地执行和远程 API 代理提供了一个统一的接口。

标题：CogneeClient 执行流程

graph TB
    subgraph "MCP 工具逻辑"
        ToolRemember["remember() 工具"]
        ToolRecall["recall() 工具"]
    end

    subgraph "CogneeClient 方法"
        ClientAdd["CogneeClient.add()"]
        ClientCognify["CogneeClient.cognify()"]
        ClientSearch["CogneeClient.search()"]
    end

    subgraph "执行模式"
        ModeCheck{"self.use_api"}

        subgraph "直接模式"
            DirectCall["直接 Python 调用<br/>await self.cognee.add()"]
        end

        subgraph "API 模式"
            APICall["HTTP 请求<br/>await self.client.post('/api/v1/add')"]
        end
    end

    ToolRemember --> ClientAdd
    ToolRemember --> ClientCognify
    ToolRecall --> ClientSearch

    ClientAdd --> ModeCheck
    ClientCognify --> ModeCheck
    ClientSearch --> ModeCheck

    ModeCheck -->|"True"| APICall
    ModeCheck -->|"False"| DirectCall

来源：cognee-mcp/src/cognee_client.py:44-68、cognee-mcp/src/cognee_client.py:107-155

模式选择逻辑

如果在初始化时提供了 api_url，客户端会切换到 API 模式，否则默认使用直接模式并导入本地 cognee 包 cognee-mcp/src/cognee_client.py:44-68。

配置与启动

环境变量

服务器配置主要由环境变量驱动，尤其是在 Docker 中运行时 cognee-mcp/entrypoint.sh:45-57。

变量	默认值	描述
TRANSPORT_MODE	stdio	传输协议（stdio、sse、http）
HTTP_PORT	8000	网络传输的绑定端口
API_URL	None	远程 Cognee API 服务器的 URL
EXTRAS	None	运行时安装的可选依赖组

传输安全

Cognee 实现了 DNS 重绑定保护以及 Host/Origin 请求头校验，用于网络传输 cognee-mcp/src/server.py:106-154。

• DNS 重绑定保护：默认启用，除非 MCP_DISABLE_DNS_REBINDING_PROTECTION 设置为 "true" cognee-mcp/src/server.py:119-126。
• 允许的主机：可通过 MCP_ALLOWED_HOSTS 环境变量配置 cognee-mcp/src/server.py:128-136。

来源：cognee-mcp/src/server.py:106-154、cognee-mcp/entrypoint.sh:44-57

Docker 部署

MCP 服务器以多阶段 Docker 镜像形式分发 cognee-mcp/Dockerfile:1-13。

镜像入口点

entrypoint.sh 脚本负责环境设置，包括将 API_URL 中的 localhost 转换为 host.docker.internal，以便与宿主机上运行的服务进行通信 cognee-mcp/entrypoint.sh:62-81。

可选依赖： 如果设置了 EXTRAS 环境变量，可以在运行时使用 uv pip install 安装可选依赖组（例如 postgres、neo4j）cognee-mcp/entrypoint.sh:6-40。

来源：cognee-mcp/Dockerfile:1-94、cognee-mcp/entrypoint.sh:1-102