部署Didit MCP服务器：Docker与Node.js自托管指南

主要收获

• Didit模型上下文协议（MCP）服务器是基于MIT许可证的开源项目。您可以从其公共GitHub仓库构建，并通过Docker、Node.js或无头stdio传输运行。
• 自托管改变了MCP进程的运行位置，而不是它如何连接到Didit。每种模式都以带有Bearer访问令牌的Didit用户身份进行认证。MCP工具没有应用程序API密钥模式。
• 完整的自托管目录包含121个工具。托管的开放授权（OAuth）端点有意暴露了115个。当前源代码中的示例包括didit_context_get、didit_session_create和didit_transaction_screen_wallet。
• HTTP入口是无状态的，并通过POST请求接受MCP流量。每个请求都会创建一个新的服务器和传输，因此负载均衡器不需要会话粘性。
• 使用/healthz进行容器和负载均衡器检查。在暴露服务之前，明确配置公共资源URI、授权源、令牌验证模式和密钥。

托管端点很方便，但并非每个团队都适合将其作为运营选择。企业可能需要将集成保留在其自己的网络边界内，控制运行时镜像，通过私有出口层路由流量，或者应用其自己的可观测性和变更管理策略。Didit MCP仓库支持这种部署模型，而无需创建单独的产品界面。

本指南仅关注服务器的运行。有关目录和工具行为，请参阅Didit MCP工具参考。有关针对托管端点的客户端设置，请参阅Claude安装指南。完整的技术参考可在MCP概述和认证文档中找到。

选择HTTP或stdio入口

该仓库构建了一个共享工具目录，带有两个入口点。dist/http.js通过无状态可流式HTTP运行Express资源服务器。对于由多个MCP客户端、容器或用户访问的共享服务来说，这是正确的选择。dist/index.js通过stdio运行，旨在用于由一个客户端启动的无头本地进程。

两个入口点都调用相同的分派逻辑，并且版本5仅暴露MCP工具——不暴露MCP资源或提示。两者都以Didit用户身份验证下游请求。不同之处在于该用户凭据如何到达进程：HTTP入口接收并验证调用者的OAuth Bearer令牌；stdio入口从DIDIT_ACCESS_TOKEN读取用户Bearer令牌。

自托管并不意味着无需凭据：MCP仍然作为Didit用户行事，Didit将该用户的组织角色和权限应用于每次工具调用。

使用Docker构建并运行

该仓库包含一个基于Node 20的多阶段Dockerfile。构建阶段安装开发依赖项，编译TypeScript，并修剪开发包。生产阶段以非root用户node运行，并包含容器健康检查。

git clone https://github.com/didit-protocol/mcp.git
cd mcp
cp .env.example .env

docker build -t didit-mcp .
docker run -p 3000:3000 --env-file .env didit-mcp

在启动容器之前，替换标识您部署的托管默认值。至少将MCP_RESOURCE_URI设置为客户端通过其访问此资源服务器的公共源，然后提供令牌自省所需的OAuth客户端凭据。将密钥保存在您的容器平台的密钥管理器中，而不是提交已填充的.env文件。

MCP_PORT=3000
MCP_RESOURCE_URI=https://mcp.example.com
MCP_AUTHORIZATION_SERVER_ORIGIN=https://business.didit.me
MCP_TOKEN_VERIFY_MODE=introspection
MCP_OAUTH_CLIENT_ID=replace-with-client-id
MCP_OAUTH_CLIENT_SECRET=replace-with-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"

在您的入口或负载均衡器处终止传输层安全（TLS），将MCP POST请求转发到端口3000，并保留Authorization头。外部可见的MCP_RESOURCE_URI必须与向客户端通告的资源身份匹配；不要为不同的公共源保留托管的Didit URI。

直接使用Node.js构建并运行

如果您的平台已经管理Node运行时，则可以使用相同的HTTP入口点而无需容器。该包是私有的，不通过npm分发，因此请克隆仓库而不是尝试执行已发布的包。

git clone https://github.com/didit-protocol/mcp.git
cd mcp
npm install
npm run build
node dist/http.js

该进程读取与容器相同的环境变量。在您的进程管理器下运行它，通过部署环境注入密钥，并仅路由所需的端点。MCP请求发送到POST /mcp。该服务故意拒绝该路由上的GET和DELETE请求，因为它不维护MCP会话或服务器启动的流。

Node.js不会自动加载仓库的.env文件。在启动dist/http.js之前，在shell中导出这些值，通过服务管理器注入它们，或使用您平台的配置文件支持。另请注意，npm start启动stdio入口点；对于HTTP，请使用node dist/http.js或npm run start:http。

通过stdio无头运行

对于本地代理、构建运行器或隔离的单客户端进程，请使用stdio入口点。通过环境提供用户访问令牌，并让MCP客户端拥有进程生命周期。

DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js

此令牌是用户Bearer凭据，而不是应用程序凭据。将其作为密钥存储，避免出现在shell历史记录和日志中，并根据您的访问策略进行轮换。如果一个部署始终在一个组织或应用程序中运行，MCP_DEFAULT_ORG和MCP_DEFAULT_APP可以提供该默认范围。否则，工具可以从显式参数或经过身份验证的请求上下文中解析范围。

stdio中仍然没有应用程序API密钥模式。自托管HTTP和自托管stdio都调用用户范围的Didit控制台端点，因此应用程序密钥不能替代用户Bearer令牌。

配置完整的环境表面

当前的src/config.ts支持以下变量。大多数部署应保留生产Didit API和授权默认值，并仅覆盖其拓扑所需的资源身份、验证配置和密钥。

共享和stdio变量

• DIDIT_ACCESS_TOKEN：无头stdio模式的用户Bearer令牌；无默认值。
• DIDIT_API_BASE_URL：验证API基础URL；默认为https://verification.didit.me/v3。
• DIDIT_AUTH_BASE_URL：认证API基础URL；默认为https://apx.didit.me/auth/v2。
• MCP_DEFAULT_ORG和MCP_DEFAULT_APP：单租户部署的可选组织和应用程序默认值。

HTTP资源服务器变量

• MCP_PORT：监听端口；默认为3000。
• MCP_RESOURCE_URI：公共资源服务器URI；默认为https://mcp.didit.me。
• MCP_AUTHORIZATION_SERVER_ORIGIN：授权服务器源；默认为https://business.didit.me。
• MCP_TOKEN_VERIFY_MODE：默认为introspection，或当授权服务发布适合本地签名验证的JSON Web Tokens (JWTs)时为jwks。
• MCP_OAUTH_CLIENT_ID和MCP_OAUTH_CLIENT_SECRET：无默认值；用作RFC 7662自省的HTTP基本凭据。
• MCP_OAUTH_INTROSPECT_URL：默认为https://apx.didit.me/auth/v2/introspect/。
• MCP_SCOPES_SUPPORTED：以空格分隔的发现范围；默认为didit:management didit:verification。

授权元数据覆盖

• DIDIT_AUTH_ISSUER：默认为MCP_AUTHORIZATION_SERVER_ORIGIN。
• DIDIT_OIDC_DISCOVERY_URL：OpenID Connect (OIDC)发现文档；默认为授权源加上/.well-known/oauth-authorization-server。
• DIDIT_JWKS_URL：JSON Web Key Set (JWKS)端点；默认为https://apx.didit.me/auth/config/jwks/。
• DIDIT_OIDC_AUTHORIZE_URL：默认为授权源加上/authorize。
• DIDIT_OIDC_TOKEN_URL：默认为授权源加上/api/auth/oauth-token。
• DIDIT_OIDC_REGISTRATION_URL：默认为授权源加上/api/auth/oauth-register。

对于不透明的访问令牌，请使用introspection。服务器使用MCP_OAUTH_CLIENT_ID和MCP_OAUTH_CLIENT_SECRET将它们发送到配置的自省端点。仅当您的授权服务配置为为此客户端颁发已签名的JWT访问令牌时，才使用jwks；服务器随后根据DIDIT_JWKS_URL验证签名。更改验证模式不会创建不同的身份模型：经过验证的主体仍然是Didit用户。

MCP客户端可以在其授权流程中使用Didit商业控制台进行动态客户端注册（DCR）。该客户端注册与资源服务器的MCP_OAUTH_CLIENT_ID和MCP_OAUTH_CLIENT_SECRET是分开的，后者用于验证自省请求。通过适当的Didit部署渠道提供这些服务器端凭据，而不是假设客户端注册可以替代它们。

健康检查和无状态扩展

HTTP进程暴露GET /healthz并返回包含status、service和version的JSON。Docker镜像已在15秒启动后每30秒检查一次。您可以使用相同的端点进行Kubernetes就绪性检查、应用程序负载均衡器目标组或外部正常运行时间探测。

curl -fsS http://localhost:3000/healthz

MCP路由设计为无状态。对于每个经过身份验证的POST请求，进程都会创建一个新的服务器和可流式HTTP传输（禁用会话生成），通过每个请求上下文转发调用者的已验证凭据，完成分派，并关闭传输。没有内存中的会话是后续请求必须在同一副本上找到的。

此处，无状态描述的是MCP传输和请求生命周期。验证会话、工作流、案例和其他业务记录仍然保留在Didit的上游服务中。

因此，水平副本不需要粘性会话。任何健康的实例都可以处理下一个POST请求，滚动部署不需要超出普通进行中请求处理的会话清空。容量规划应侧重于请求并发性、下游Didit API延迟以及您的正常超时和重试策略。

在暴露服务前进行验证

• 确认/healthz从与负载均衡器相同的网络路径成功。
• 确认未经身份验证的MCP请求收到授权挑战而不是工具输出。
• 完成带有代码交换证明密钥（PKCE）的OAuth 2.1流程，然后调用didit_context_get以验证预期的组织和应用程序是否可见。
• 在更改发现端点或令牌验证之前，请查阅高级MCP文档。
• 使用Didit MCP开发者页面获取支持的托管界面和当前链接。

如果自托管不再是要求，托管端点将消除上述运行时和OAuth资源服务器操作。Claude用户可以通过Didit连接器深层链接添加它。无论您运行进程还是Didit运行，核心规则都是相同的：MCP操作以Didit用户身份进行身份验证，而不是以应用程序API密钥身份进行身份验证。