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 模式（本地）

1.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。

1.2 Windows 配置

Trae

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "memory-center": {
      "command": "d:/path/to/target/release/memory-center-mcp.exe",
      "env": {
        "MEMORY_CENTER_ROOT": "d:/path/to/memory/data"
      }
    }
  }
}

路径分隔符：Windows 路径建议用正斜杠 /（JSON 标准），也支持反斜杠 \\（需双重转义）。 不要用单反斜杠 \（JSON 会将其视为转义符）。

Claude Code

编辑 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "memory-center": {
      "command": "d:/path/to/target/release/memory-center-mcp.exe",
      "env": {
        "MEMORY_CENTER_ROOT": "d:/path/to/memory/data"
      }
    }
  }
}

Cursor

在项目根目录创建 .cursor/mcp.json，格式同 Trae。

1.3 Linux 配置

Claude Code

编辑 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "memory-center": {
      "command": "/home/user/memory-center/target/release/memory-center-mcp",
      "env": {
        "MEMORY_CENTER_ROOT": "/home/user/memory-center/data"
      }
    }
  }
}

Trae（Linux）

同 Windows，路径改为 Linux 风格即可。

1.4 启用 LLM 增强（可选，推荐）

默认使用启发式降级（无 LLM 调用）。配置 LLM 后启用完整能力：

{
  "mcpServers": {
    "memory-center": {
      "command": "/path/to/memory-center-mcp",
      "env": {
        "MEMORY_CENTER_ROOT": "/path/to/data",
        "MEMORY_CENTER_GENERATOR_API_URL": "https://api.deepseek.com/v1/chat/completions",
        "MEMORY_CENTER_GENERATOR_API_KEY": "sk-xxx",
        "MEMORY_CENTER_GENERATOR_MODEL": "deepseek-chat",
        "MEMORY_CENTER_DETECTOR_API_URL": "https://api.deepseek.com/v1/chat/completions",
        "MEMORY_CENTER_DETECTOR_API_KEY": "sk-xxx",
        "MEMORY_CENTER_DETECTOR_MODEL": "deepseek-chat",
        "MEMORY_CENTER_EMBEDDER_API_URL": "https://api.deepseek.com/v1/embeddings",
        "MEMORY_CENTER_EMBEDDER_API_KEY": "sk-xxx",
        "MEMORY_CENTER_EMBEDDER_MODEL": "text-embedding-3-small"
      }
    }
  }
}
组件 环境变量 未配置时的降级
摘要生成器 MEMORY_CENTER_GENERATOR_* 启发式摘要（首条消息前 80 字符）
冲突检测器 MEMORY_CENTER_DETECTOR_* 启发式纯算法（三维度检测）
语义检索 MEMORY_CENTER_EMBEDDER_* 仅 BM25 关键词检索

1.5 验证 stdio 模式

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

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

如果报错，查看 常见问题排查。

二、Streamable HTTP 模式（远程服务器直连）

2.1 服务器端配置

构建 Binary

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

systemd 服务

创建 /etc/systemd/system/memory-center.service：

[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
Environment=MEMORY_CENTER_MCP_ENABLED=true
Environment=MEMORY_CENTER_MCP_STATEFUL=true
Environment=MEMORY_CENTER_MCP_ALLOWED_HOSTS=your-domain.com,localhost,127.0.0.1
Environment=MEMORY_CENTER_MCP_ALLOWED_ORIGINS=https://your-domain.com
Environment=MEMORY_CENTER_GENERATOR_API_URL=https://api.deepseek.com/v1/chat/completions
Environment=MEMORY_CENTER_GENERATOR_API_KEY=sk-xxx
Environment=MEMORY_CENTER_GENERATOR_MODEL=deepseek-chat
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

关键环境变量：

  • MEMORY_CENTER_MCP_ENABLED=true：启用 /mcp 端点（默认 false）
  • MEMORY_CENTER_MCP_ALLOWED_HOSTS：必须包含你的域名，否则报 403

Nginx 反代配置

# /etc/nginx/sites-available/memory-center
server {
    listen 80;
    server_name your-domain.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;
        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_read_timeout 300s 是 SSE 流式响应必需的， 否则客户端会超时断开。

2.2 客户端配置

{
  "mcpServers": {
    "memory-center": {
      "url": "http://your-domain.com/mcp"
    }
  }
}

无 CDN 时用 HTTP：如果服务器没有 CDN，直接用 http://。 有 CDN 时看 Cloudflare CDN 代理 章节。

2.3 验证 HTTP 模式

# 测试 MCP initialize
curl -s -X POST http://your-domain.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}'

# 预期返回（SSE 流格式）：
# data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"memory-center-mcp","version":"0.1.0"}}}

三、Cloudflare CDN 代理

3.1 HTTPS 重定向陷阱（重要）

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

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

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

{
  "mcpServers": {
    "memory-center": {
      "url": "https://your-domain.com/mcp"
    }
  }
}

3.2 Cloudflare SSL 模式

Cloudflare 回源到服务器有三种 SSL 模式：

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

推荐用 Flexible 模式（最简单）：

  • Cloudflare 客户端 ← HTTPS → Cloudflare
  • Cloudflare ← HTTP → 你的服务器 Nginx（监听 80）
  • 服务器无需配置 SSL 证书

3.3 完整配置（Cloudflare + Flexible SSL）

服务器 Nginx（只监听 80）：

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

    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 "";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }
}

systemd 环境变量：

Environment=MEMORY_CENTER_MCP_ALLOWED_HOSTS=your-domain.com,localhost,127.0.0.1
# Origins 留空，Cloudflare 回源不带 Origin
Environment=MEMORY_CENTER_MCP_ALLOWED_ORIGINS=

客户端配置（HTTPS）：

{
  "mcpServers": {
    "memory-center": {
      "url": "https://your-domain.com/mcp"
    }
  }
}

3.4 Cloudflare 防火墙规则（可选）

为提高安全性，可在 Cloudflare 设置防火墙规则，只允许特定 IP 访问 /mcp 端点：

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

四、Docker 容器

4.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"]

# HTTP API + MCP 端点
EXPOSE 8765

ENV MEMORY_CENTER_ROOT=/data
ENV MEMORY_CENTER_MCP_ENABLED=true
ENV MEMORY_CENTER_MCP_STATEFUL=true
ENV MEMORY_CENTER_MCP_ALLOWED_HOSTS=*

CMD ["memory-center-server"]

4.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
      MEMORY_CENTER_MCP_ENABLED: "true"
      MEMORY_CENTER_MCP_STATEFUL: "true"
      MEMORY_CENTER_MCP_ALLOWED_HOSTS: "*"  # Docker 内网不限制 Host
      MEMORY_CENTER_MCP_ALLOWED_ORIGINS: ""
      # LLM 增强（可选）
      MEMORY_CENTER_GENERATOR_API_URL: https://api.deepseek.com/v1/chat/completions
      MEMORY_CENTER_GENERATOR_API_KEY: sk-xxx
      MEMORY_CENTER_GENERATOR_MODEL: deepseek-chat
    restart: unless-stopped

4.3 客户端配置

客户端在宿主机

{
  "mcpServers": {
    "memory-center": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

客户端在另一个容器

{
  "mcpServers": {
    "memory-center": {
      "url": "http://memory-center:8765/mcp"
    }
  }
}

Docker 内网通信时 MEMORY_CENTER_MCP_ALLOWED_HOSTS 设为 * 或包含容器名。

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

server {
    listen 80;
    server_name your-domain.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;
    }
}

五、环境变量完整参考

5.1 核心配置

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

5.2 MCP HTTP 配置

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

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

5.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（如 DeepSeek），也可分别配置不同模型。

六、常见问题排查

6.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.com/mcp"

// ✓ 正确：直接用 HTTPS
"url": "https://your-domain.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

6.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.com,localhost,127.0.0.1

6.3 405 Method Not Allowed

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

6.4 Windows 路径转义问题

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

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

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

6.5 环境变量未生效（systemd）

原因：修改 systemd 配置后未 reload

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

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

6.6 SSE 流超时断开

原因：Nginx 缓冲了 SSE 响应

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

6.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