TLS/HTTPS 设置

概述

本指南涵盖在 HTTP 传输模式下为 Neo4j MCP 服务器配置安全的 TLS/HTTPS 连接。

所有证书必须采用 PEM 格式（文本格式，包含 -----BEGIN CERTIFICATE----- 标头）。服务器不支持 DER 或 PKCS12 格式。

证书要求

格式规范

证书必须仅使用 PEM 编码。

证书颁发机构注意事项

自签名证书 在许多 MCP 客户端上无法直接使用（例如 VSCode Copilot、Claude Desktop）。这些客户端需要受信任的证书颁发机构签发的证书。

自签名证书的适用场景

  • 本地开发

  • 安全性放宽的测试环境

  • 客户端配置受控的场景

生产环境选项

  • Let’s Encrypt（免费、自动化）

  • 内部组织证书颁发机构

  • 商业证书提供商

快速开始

生成测试证书

用于本地主机测试

openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj "/CN=localhost"

针对带有主题备用名称（SAN）的特定域名

openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj "/CN=your-domain.com" \
  -addext "subjectAltName=DNS:your-domain.com,DNS:www.your-domain.com"

启动服务器

使用命令行参数

neo4j-mcp \
  --neo4j-uri bolt://:7687 \
  --neo4j-transport-mode http \
  --neo4j-http-port 8443 \
  --neo4j-http-tls-enabled true \
  --neo4j-http-tls-cert-file cert.pem \
  --neo4j-http-tls-key-file key.pem

或使用环境变量

export NEO4J_URI="bolt://:7687"
export NEO4J_MCP_TRANSPORT="http"
export NEO4J_MCP_HTTP_TLS_ENABLED="true"
export NEO4J_MCP_HTTP_TLS_CERT_FILE="cert.pem"
export NEO4J_MCP_HTTP_TLS_KEY_FILE="key.pem"
neo4j-mcp

测试 TLS 配置

基本连通性

测试根路径（返回 404）

curl -k https://127.0.0.1:8443/

测试未认证的 MCP 端点（返回 401）

curl -k https://127.0.0.1:8443/mcp

参数 -k 会绕过证书验证（在测试自签名证书时必要）。

MCP 协议验证

初始化会话

curl -k -u neo4j:password \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    },
    "id": 1
  }' \
  https://127.0.0.1:8443/mcp

列出可用工具

curl -k -u neo4j:password \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' \
  https://127.0.0.1:8443/mcp

TLS 验证

检查证书细节

openssl s_client -connect 127.0.0.1:8443 -showcerts | openssl x509 -text -noout

检查 TLS 协议版本

openssl s_client -connect 127.0.0.1:8443 -tls1_3 | grep "Protocol"

配置说明

  • 参数 -k 会绕过证书验证（自签名证书时必要）

  • 需要使用 -u username:password 提供基本身份验证凭据

  • TLS 启用时默认端口为 443，禁用时为 80

  • 服务器仅处理对 /mcp 的请求；其他路径返回 404

  • TLS 配置强制最低 TLS 1.2，并使用安全的默认密码套件

生产部署

在生产环境中，请使用来自受信任证书颁发机构（如 Let’s Encrypt）的证书

neo4j-mcp \
  --neo4j-uri bolt://:7687 \
  --neo4j-transport-mode http \
  --neo4j-http-port 443 \
  --neo4j-http-tls-enabled true \
  --neo4j-http-tls-cert-file /etc/letsencrypt/live/your-domain.com/fullchain.pem \
  --neo4j-http-tls-key-file /etc/letsencrypt/live/your-domain.com/privkey.pem

证书的通用名称（CN）和主题备用名称（SAN）必须与客户端连接时使用的域名相匹配。

使用受信任的证书后，客户端可以在不绕过证书验证的情况下连接

curl -u neo4j:password https://your-domain.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

另见