Skip to content

MCP Configuration Guide

Jump to bottom
LINGTIAN303 edited this page Jul 8, 2026 · 2 revisions

MCP 配置指南

本文档详细说明 MemoryCenter MCP Server 在不同模式、不同环境下的配置方法。 如果你是第一次接入，先看 MCP Integration 了解概览，再按本文档配置。

模式选择决策树

你的 MCP 客户端在哪里运行？
│
├─ 本地（与 MemoryCenter 同一台机器）
│   │
│   ├─ 是 IDE（Claude Code / Cursor / Trae / Codex CLI）
│   │   └─→ stdio 模式（推荐，零网络开销）
│   │
│   └─ 是 Web Agent（浏览器端）
│       └─→ Streamable HTTP 模式（本地 127.0.0.1）
│
└─ 远程（与 MemoryCenter 不同机器）
    │
    ├─ 服务器有公网域名 + CDN
    │   └─→ Streamable HTTP + Cloudflare CDN（推荐，自动 HTTPS）
    │
    ├─ 服务器有公网 IP，无 CDN
    │   └─→ Streamable HTTP + Nginx 反代（需自配 SSL 或用 HTTP）
    │
    └─ 服务器在内网 / Docker 容器
        └─→ Streamable HTTP，客户端通过 SSH 隧道或内网直连
模式 Binary 传输方式 适用场景
stdio memory-center-mcp 子进程 stdin/stdout 本地 IDE，零网络开销
Streamable HTTP memory-center-server HTTP POST + SSE 远程客户端、Web Agent、多客户端共享

一、通用配置（所有模式共用）

无论 stdio 还是 HTTP 模式，以下环境变量都适用。配置一次，两种模式共用，后续章节不再重复。

1.1 核心环境变量

# 记忆数据存储根目录（必填，指向可写目录）
MEMORY_CENTER_ROOT=/path/to/data

# REST API 鉴权密钥（生产环境必填，本地调试可留空表示不鉴权）
MEMORY_CENTER_API_KEY=your-api-key-here

1.2 LLM 增强（可选，推荐）

默认使用启发式降级（无 LLM 调用）。配置 LLM 后启用完整能力。三个组件可共用同一个 API。

# === 摘要生成器（未配置时降级为启发式摘要：首条消息前 80 字符） ===
MEMORY_CENTER_GENERATOR_API_URL=https://your-llm-api.example.com/v1/chat/completions  # LLM Chat API 地址
MEMORY_CENTER_GENERATOR_API_KEY=sk-your-key-here                                       # API 密钥
MEMORY_CENTER_GENERATOR_MODEL=your-model-name                                          # 模型名

# === 冲突检测器（未配置时降级为启发式纯算法：三维度检测） ===
MEMORY_CENTER_DETECTOR_API_URL=https://your-llm-api.example.com/v1/chat/completions    # LLM Chat API 地址
MEMORY_CENTER_DETECTOR_API_KEY=sk-your-key-here                                        # API 密钥
MEMORY_CENTER_DETECTOR_MODEL=your-model-name                                           # 模型名

# === 语义嵌入（未配置时降级为仅 BM25 关键词检索） ===
MEMORY_CENTER_EMBEDDER_API_URL=https://your-llm-api.example.com/v1/embeddings          # Embedding API 地址
MEMORY_CENTER_EMBEDDER_API_KEY=sk-your-key-here                                        # API 密钥
MEMORY_CENTER_EMBEDDER_MODEL=your-embedding-model                                      # 嵌入模型名
组件 环境变量前缀 未配置时降级
摘要生成器 MEMORY_CENTER_GENERATOR_* 启发式摘要（首条消息前 80 字符）
冲突检测器 MEMORY_CENTER_DETECTOR_* 启发式纯算法（三维度检测）
语义检索 MEMORY_CENTER_EMBEDDER_* 仅 BM25 关键词检索

二、stdio 模式（本地 IDE）

2.1 构建 Binary

# 构建 stdio 模式 binary
cargo build --release -p memory-center-mcp

# 产物路径：
#   Linux/macOS: target/release/memory-center-mcp
#   Windows:     target/release/memory-center-mcp.exe

注意 binary 名称：是 memory-center-mcp（带连字符），不是 memorycenter-mcp（无连字符）。 拼写错误会导致客户端找不到 binary，报 Connection closed。

2.2 客户端配置（三种 IDE 通用）

三种 IDE 配置格式相同，只是配置文件位置不同：

IDE 配置文件位置
Trae 项目根目录 .mcp.json
Claude Code ~/.claude/claude_desktop_config.json
Cursor 项目根目录 .cursor/mcp.json

配置内容（Windows 示例，Linux 路径改为 /home/user/...）：

{
  "mcpServers": {
    "memory-center": {
      "command": "d:/path/to/target/release/memory-center-mcp.exe",  // binary 完整路径（Windows 用正斜杠 /）
      "env": {
        "MEMORY_CENTER_ROOT": "d:/path/to/memory/data",              // 记忆数据存储目录
        "MEMORY_CENTER_GENERATOR_API_URL": "https://your-llm-api.example.com/v1/chat/completions",  // 摘要 LLM API
        "MEMORY_CENTER_GENERATOR_API_KEY": "sk-your-key-here",       // 摘要 LLM 密钥
        "MEMORY_CENTER_GENERATOR_MODEL": "your-model-name",          // 摘要 LLM 模型名
        "MEMORY_CENTER_DETECTOR_API_URL": "https://your-llm-api.example.com/v1/chat/completions",   // 冲突检测 LLM API
        "MEMORY_CENTER_DETECTOR_API_KEY": "sk-your-key-here",        // 冲突检测 LLM 密钥
        "MEMORY_CENTER_DETECTOR_MODEL": "your-model-name",           // 冲突检测 LLM 模型名
        "MEMORY_CENTER_EMBEDDER_API_URL": "https://your-llm-api.example.com/v1/embeddings",         // 语义嵌入 API
        "MEMORY_CENTER_EMBEDDER_API_KEY": "sk-your-key-here",        // 语义嵌入密钥
        "MEMORY_CENTER_EMBEDDER_MODEL": "your-embedding-model"       // 嵌入模型名
      }
    }
  }
}

路径分隔符：Windows 路径用正斜杠 /（推荐）或双反斜杠 \\，不要用单反斜杠 \（JSON 转义符）。

LLM 配置可选：不配置 GENERATOR_* / DETECTOR_* / EMBEDDER_* 时自动降级为启发式模式，功能可用但效果减弱。

2.3 验证

配置完成后重启 IDE，检查 MCP 服务器是否加载：

  • Trae：设置 → MCP 服务器 → memory-center 状态应为 "connected"
  • Claude Code：/mcp 命令查看已连接的 MCP 服务器
  • Cursor：设置 → MCP → 查看状态

三、Streamable HTTP 模式（远程服务器）

3.1 构建 Binary

cargo build --release -p memory-center-server
# 产物：target/release/memory-center-server

3.2 MCP HTTP 专用环境变量

除 通用配置 外，HTTP 模式还需要以下变量：

# 是否启用 /mcp 端点（默认 false，必须显式开启）
MEMORY_CENTER_MCP_ENABLED=true

# 是否启用 session 模式，支持 SSE 流式响应（默认 true）
MEMORY_CENTER_MCP_STATEFUL=true

# 允许的 Host 列表，逗号分隔（DNS rebinding 防护，必须包含你的域名，否则 403）
MEMORY_CENTER_MCP_ALLOWED_HOSTS=your-domain.example.com,localhost,127.0.0.1

# 允许的 Origin 列表，逗号分隔（CORS 防护，空表示不校验）
MEMORY_CENTER_MCP_ALLOWED_ORIGINS=

MEMORY_CENTER_MCP_ALLOWED_HOSTS 必须包含你的域名，否则报 403 Forbidden。 Docker 内网可设为 *（不限制）。

3.3 systemd 服务配置

创建 /etc/systemd/system/memory-center.service（环境变量含义见 通用配置 和 3.2 节）：

[Unit]
Description=MemoryCenter HTTP Server
After=network.target

[Service]
Type=simple
ExecStart=/opt/memory-center/bin/memory-center-server

# 核心配置
Environment=MEMORY_CENTER_ROOT=/opt/memory-center/data
Environment=MEMORY_CENTER_API_KEY=your-api-key-here

# MCP HTTP 专用
Environment=MEMORY_CENTER_MCP_ENABLED=true
Environment=MEMORY_CENTER_MCP_STATEFUL=true
Environment=MEMORY_CENTER_MCP_ALLOWED_HOSTS=your-domain.example.com,localhost,127.0.0.1
Environment=MEMORY_CENTER_MCP_ALLOWED_ORIGINS=

# LLM 增强（可选，三项可共用同一 API）
Environment=MEMORY_CENTER_GENERATOR_API_URL=https://your-llm-api.example.com/v1/chat/completions
Environment=MEMORY_CENTER_GENERATOR_API_KEY=sk-your-key-here
Environment=MEMORY_CENTER_GENERATOR_MODEL=your-model-name
Environment=MEMORY_CENTER_DETECTOR_API_URL=https://your-llm-api.example.com/v1/chat/completions
Environment=MEMORY_CENTER_DETECTOR_API_KEY=sk-your-key-here
Environment=MEMORY_CENTER_DETECTOR_MODEL=your-model-name
Environment=MEMORY_CENTER_EMBEDDER_API_URL=https://your-llm-api.example.com/v1/embeddings
Environment=MEMORY_CENTER_EMBEDDER_API_KEY=sk-your-key-here
Environment=MEMORY_CENTER_EMBEDDER_MODEL=your-embedding-model

Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

3.4 Nginx 反代配置

server {
    listen 80;
    server_name your-domain.example.com;

    # MCP Streamable HTTP 端点
    location /mcp {
        proxy_pass http://127.0.0.1:8765;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Connection "";
        # SSE 长连接支持（三项缺一不可）
        proxy_buffering off;       # 关闭缓冲，否则 SSE 流被缓存
        proxy_cache off;           # 关闭缓存
        proxy_read_timeout 300s;   # 长连接超时（秒）
    }

    # REST API
    location /memory-center/ {
        proxy_pass http://127.0.0.1:8765/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

SSE 支持关键：proxy_buffering off + proxy_cache off + proxy_read_timeout 300s 三项缺一不可， 否则客户端会超时断开。

3.5 客户端配置

无 CDN（直连服务器）：

{
  "mcpServers": {
    "memory-center": {
      "url": "http://your-domain.example.com/mcp"  // 服务器 HTTP 地址
    }
  }
}

有 CDN（如 Cloudflare）：必须用 HTTPS，详见 第四章。

3.6 验证 HTTP 模式

# 测试 MCP initialize（应返回 SSE 流包含 serverInfo）
curl -s -X POST http://your-domain.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

四、Cloudflare CDN 代理

4.1 HTTPS 重定向陷阱（重要）

问题：Cloudflare 默认开启 "Always Use HTTPS"，会把 HTTP 请求 301 重定向到 HTTPS。 MCP Streamable HTTP 客户端不处理 301 重定向，导致 Connection closed。

客户端配置 http://your-domain.example.com/mcp
  → Cloudflare 返回 301 → https://your-domain.example.com/mcp
    → MCP 客户端不跟随重定向 → Connection closed ✗

解决方案：客户端配置直接用 HTTPS。

{
  "mcpServers": {
    "memory-center": {
      "url": "https://your-domain.example.com/mcp"  // CDN 必须用 HTTPS
    }
  }
}

4.2 Cloudflare SSL 模式选择

模式 回源协议 服务器是否需要 SSL 推荐度
Flexible HTTP 否（Nginx 监听 80） ★★★（最简单）
Full HTTPS 是（需自签证书） ★★
Full (strict) HTTPS 是（需有效证书） ★★★★（最安全）

推荐 Flexible 模式（最简单）：客户端 ← HTTPS → Cloudflare ← HTTP → 你的服务器（Nginx 只监听 80，无需 SSL 证书）。

4.3 完整配置（Flexible SSL）

服务器 Nginx：只监听 80，配置同 3.4 节。

systemd 环境变量：同 3.3 节，ALLOWED_ORIGINS 留空（Cloudflare 回源不带 Origin）。

客户端配置（HTTPS）：

{
  "mcpServers": {
    "memory-center": {
      "url": "https://your-domain.example.com/mcp"  // CDN 必须用 HTTPS
    }
  }
}

4.4 Cloudflare 防火墙规则（可选）

规则：URI Path equals "/mcp" AND IP Source Address is not in {allowed_ips}
动作：Block

五、Docker 容器

5.1 Dockerfile

FROM rust:1.88-slim AS builder

WORKDIR /app
COPY . .
RUN cargo build --release -p memory-center-server

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates libssl3 && rm -rf /var/lib/apt/lists/*

COPY --from=builder /app/target/release/memory-center-server /usr/local/bin/

VOLUME ["/data"]           # 记忆数据持久化目录
EXPOSE 8765                # HTTP API + MCP 端口

# 默认环境变量（运行时可通过 -e 覆盖）
ENV MEMORY_CENTER_ROOT=/data
ENV MEMORY_CENTER_MCP_ENABLED=true
ENV MEMORY_CENTER_MCP_STATEFUL=true
ENV MEMORY_CENTER_MCP_ALLOWED_HOSTS=*   # Docker 内网不限制 Host

CMD ["memory-center-server"]

5.2 docker-compose.yml

version: "3.8"

services:
  memory-center:
    build: .
    container_name: memory-center
    ports:
      - "8765:8765"                    # 映射端口到宿主机
    volumes:
      - ./data:/data                   # 数据持久化
    environment:
      # 核心配置
      MEMORY_CENTER_ROOT: /data
      MEMORY_CENTER_API_KEY: your-api-key-here           # REST API 鉴权密钥

      # MCP HTTP 专用
      MEMORY_CENTER_MCP_ENABLED: "true"                  # 启用 /mcp 端点
      MEMORY_CENTER_MCP_STATEFUL: "true"                 # 启用 session 模式
      MEMORY_CENTER_MCP_ALLOWED_HOSTS: "*"               # Docker 内网不限制
      MEMORY_CENTER_MCP_ALLOWED_ORIGINS: ""

      # LLM 增强（可选，参见通用配置章节）
      MEMORY_CENTER_GENERATOR_API_URL: https://your-llm-api.example.com/v1/chat/completions
      MEMORY_CENTER_GENERATOR_API_KEY: sk-your-key-here
      MEMORY_CENTER_GENERATOR_MODEL: your-model-name

    restart: unless-stopped

LLM 配置去重：Docker 的 LLM 配置与 通用配置 完全相同，此处仅展示 GENERATOR_* 作为示例， DETECTOR_* 和 EMBEDDER_* 按相同格式添加即可。

5.3 客户端配置

客户端在宿主机：

{
  "mcpServers": {
    "memory-center": {
      "url": "http://127.0.0.1:8765/mcp"  // 宿主机直接访问映射端口
    }
  }
}

客户端在另一个容器：

{
  "mcpServers": {
    "memory-center": {
      "url": "http://memory-center:8765/mcp"  // Docker 网络内用容器名通信
    }
  }
}

5.4 Docker + Nginx 反代（生产环境）

server {
    listen 80;
    server_name your-domain.example.com;

    location /mcp {
        proxy_pass http://memory-center:8765;   # Docker 容器名（需在同一网络）
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

六、环境变量完整参考

6.1 核心配置（所有模式）

环境变量 说明 默认值 必填
MEMORY_CENTER_ROOT 记忆数据存储根目录 无 是
MEMORY_CENTER_API_KEY REST API 鉴权密钥 无（不鉴权） 生产环境推荐

6.2 MCP HTTP 配置（仅 HTTP 模式）

环境变量 说明 默认值
MEMORY_CENTER_MCP_ENABLED 是否启用 /mcp 端点 false
MEMORY_CENTER_MCP_STATEFUL 是否启用 session 模式（SSE 流） true
MEMORY_CENTER_MCP_ALLOWED_HOSTS 允许的 Host（逗号分隔） localhost,127.0.0.1,::1
MEMORY_CENTER_MCP_ALLOWED_ORIGINS 允许的 Origin（逗号分隔） 空

6.3 LLM 组件配置（所有模式，可选）

环境变量 说明 未配置时降级
MEMORY_CENTER_GENERATOR_API_URL 摘要生成器 API 地址 启发式摘要
MEMORY_CENTER_GENERATOR_API_KEY 摘要生成器 API Key
MEMORY_CENTER_GENERATOR_MODEL 摘要生成器模型名
MEMORY_CENTER_DETECTOR_API_URL 冲突检测器 API 地址 启发式算法
MEMORY_CENTER_DETECTOR_API_KEY 冲突检测器 API Key
MEMORY_CENTER_DETECTOR_MODEL 冲突检测器模型名
MEMORY_CENTER_EMBEDDER_API_URL 语义嵌入 API 地址 仅 BM25 检索
MEMORY_CENTER_EMBEDDER_API_KEY 语义嵌入 API Key
MEMORY_CENTER_EMBEDDER_MODEL 语义嵌入模型名

三个组件可共用同一个 API，也可分别配置不同模型。

七、常见问题排查

7.1 Connection closed / MCP error -32000

原因 1：stdio 模式 binary 路径错误

// ✗ 错误：binary 名拼写错误（无连字符）
"command": "d:/path/to/memorycenter-mcp.exe"

// ✓ 正确：带连字符
"command": "d:/path/to/memory-center-mcp.exe"

原因 2：stdio 模式 binary 未构建

# 检查 binary 是否存在
ls target/release/memory-center-mcp.exe   # Windows
ls target/release/memory-center-mcp       # Linux

# 不存在则构建
cargo build --release -p memory-center-mcp

原因 3：HTTP 模式 URL 协议错误（Cloudflare 301 重定向）

// ✗ 错误：Cloudflare 会 301 重定向到 HTTPS，MCP 客户端不处理
"url": "http://your-domain.example.com/mcp"

// ✓ 正确：直接用 HTTPS
"url": "https://your-domain.example.com/mcp"

原因 4：HTTP 模式服务器未启动或端口错误

# 检查服务状态
systemctl status memory-center
ss -tlnp | grep 8765

# 测试连通性
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8765/mcp

7.2 403 Forbidden

原因：MEMORY_CENTER_MCP_ALLOWED_HOSTS 未包含域名

# ✗ 错误：默认只允许 localhost
Environment=MEMORY_CENTER_MCP_ALLOWED_HOSTS=localhost,127.0.0.1,::1

# ✓ 正确：包含实际域名
Environment=MEMORY_CENTER_MCP_ALLOWED_HOSTS=your-domain.example.com,localhost,127.0.0.1

7.3 405 Method Not Allowed

这是正常响应。/mcp 端点只接受 POST（请求）、GET（SSE 流）、DELETE（关闭 session）。 用 HEAD/PUT 等方法会返回 405。

7.4 Windows 路径转义问题

// ✗ 错误：单反斜杠被 JSON 视为转义符
"command": "d:\path\memory-center-mcp.exe"

// ✓ 正确：正斜杠（推荐）
"command": "d:/path/memory-center-mcp.exe"

// ✓ 正确：双反斜杠
"command": "d:\\path\\memory-center-mcp.exe"

7.5 环境变量未生效（systemd）

原因：修改 systemd 配置后未 reload

# 修改 .service 文件后必须执行
systemctl daemon-reload
systemctl restart memory-center

# 验证环境变量是否加载
systemctl show memory-center --property=Environment

7.6 SSE 流超时断开

原因：Nginx 缓冲了 SSE 响应

# 必须关闭缓冲
location /mcp {
    proxy_pass http://127.0.0.1:8765;
    proxy_buffering off;      # 关键
    proxy_cache off;          # 关键
    proxy_read_timeout 300s;  # 长连接超时
}

7.7 工具描述显示旧名称（缓存问题）

现象：MCP 客户端显示的工具描述中含旧版本名称。

原因：客户端缓存了旧的工具列表，未重新拉取。

解决：重启 IDE / MCP 客户端，强制重新连接 MCP 服务器拉取最新工具描述。

八、配置检查清单

部署前逐项检查：

  • Binary 名称正确：memory-center-mcp（stdio）/ memory-center-server（HTTP），带连字符
  • Binary 已构建：cargo build --release -p <crate-name> 完成
  • 路径格式正确：JSON 中用 / 或 \\，不用单 \
  • MEMORY_CENTER_ROOT 已设置：指向可写的数据目录
  • HTTP 模式：MEMORY_CENTER_MCP_ENABLED=true
  • HTTP 模式：MEMORY_CENTER_MCP_ALLOWED_HOSTS 包含你的域名
  • 有 CDN：客户端 URL 用 https://（不是 http://）
  • 无 CDN：客户端 URL 用 http://（不是 https://）
  • Nginx SSE 配置：proxy_buffering off + proxy_read_timeout 300s
  • systemd 改配置后：systemctl daemon-reload && systemctl restart memory-center
  • LLM 增强：三个组件的 API_URL / API_KEY / MODEL 都已配置（可选）

相关文档

Home

快速上手

集成指南

运维

Clone this wiki locally