How to Self-Host the Didit MCP Server

Key takeaways

• The Didit Model Context Protocol (MCP) server is open source under the MIT license. You can build it from the public GitHub repository and run it with Docker, Node.js, or a headless stdio transport.
• Self-hosting changes where the MCP process runs, not how it reaches Didit. Every mode authenticates as a Didit user with a Bearer access token. There is no application API-key mode for MCP tools.
• The full self-hosted catalogue contains 121 tools. The hosted Open Authorization (OAuth) endpoint intentionally exposes 115. Examples in the current source include didit_context_get, didit_session_create, and didit_transaction_screen_wallet.
• The HTTP entrypoint is stateless and accepts MCP traffic through POST requests. A fresh server and transport are created per request, so a load balancer does not need session affinity.
• Use /healthz for container and load-balancer checks. Configure the public resource URI, authorization origin, token verification mode, and secrets explicitly before exposing the service.

The hosted endpoint is convenient, but it is not the right operational choice for every team. An enterprise may need to keep the integration inside its own network boundary, control the runtime image, route traffic through a private egress layer, or apply its own observability and change-management policies. The Didit MCP repository supports that deployment model without creating a separate product surface.

This guide focuses only on operating the server. For the catalogue and tool behavior, use the Didit MCP tools reference. For client setup against the managed endpoint, use the Claude installation guide. The complete technical references are in the MCP overview and authentication documentation.

Choose the HTTP or stdio entrypoint

The repository builds one shared tool catalogue with two entrypoints. dist/http.js runs an Express resource server over stateless Streamable HTTP. It is the correct choice for a shared service reached by several MCP clients, containers, or users. dist/index.js runs over stdio and is intended for a headless local process launched by one client.

Both entrypoints call the same dispatch logic, and version 5 exposes MCP tools only—not MCP resources or prompts. Both authenticate downstream requests as a Didit user. The difference is how that user credential reaches the process: the HTTP entrypoint receives and validates the caller's OAuth Bearer token; the stdio entrypoint reads a user Bearer token from DIDIT_ACCESS_TOKEN.

Self-hosted does not mean credential-free: the MCP still acts as a Didit user, and Didit applies that user's organization role and permissions to every tool call.

Build and run with Docker

The repository includes a multi-stage Dockerfile based on Node 20. The build stage installs development dependencies, compiles TypeScript, and prunes development packages. The production stage runs as the non-root node user and includes a container health check.

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

Before starting the container, replace the hosted defaults that identify your deployment. At minimum, set MCP_RESOURCE_URI to the public origin through which clients reach this resource server, then provide the OAuth client credentials needed for token introspection. Keep secrets in your container platform's secret manager rather than committing the populated .env file.

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"

Terminate Transport Layer Security (TLS) at your ingress or load balancer, forward MCP POST requests to port 3000, and preserve the Authorization header. The externally visible MCP_RESOURCE_URI must match the resource identity advertised to clients; do not leave the managed Didit URI in place for a different public origin.

Build and run directly with Node.js

If your platform already manages a Node runtime, use the same HTTP entrypoint without a container. The package is private and is not distributed through npm, so clone the repository rather than trying to execute a published package.

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

The process reads the same environment variables as the container. Run it under your process supervisor, inject secrets through the deployment environment, and route only the required endpoints. MCP requests go to POST /mcp. The service deliberately rejects GET and DELETE on that route because it does not maintain MCP sessions or server-initiated streams.

Node.js does not load the repository's .env file automatically. Export the values in the shell, inject them through the service manager, or use your platform's environment-file support before starting dist/http.js. Also note that npm start launches the stdio entrypoint; use node dist/http.js or npm run start:http for HTTP.

Run headless over stdio

For a local agent, build runner, or isolated single-client process, use the stdio entrypoint. Supply a user access token through the environment and let the MCP client own the process lifecycle.

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

This token is a user Bearer credential, not an application credential. Store it as a secret, keep it out of shell history and logs, and rotate it according to your access policy. If one deployment always operates in one organization or application, MCP_DEFAULT_ORG and MCP_DEFAULT_APP can supply that default scope. Otherwise, tools can resolve scope from explicit arguments or the authenticated request context.

There is still no application API-key mode in stdio. Self-hosted HTTP and self-hosted stdio both call user-scoped Didit console endpoints, so an application key cannot substitute for the user Bearer token.

Configure the complete environment surface

The current src/config.ts supports the following variables. Most deployments should keep the production Didit API and authorization defaults and override only the resource identity, verification configuration, and secrets needed for their topology.

Shared and stdio variables

• DIDIT_ACCESS_TOKEN: user Bearer token for headless stdio mode; no default.
• DIDIT_API_BASE_URL: verification API base; defaults to https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL: authentication API base; defaults to https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG and MCP_DEFAULT_APP: optional organization and application defaults for single-tenant deployments.

HTTP resource-server variables

• MCP_PORT: listen port; defaults to 3000.
• MCP_RESOURCE_URI: public resource-server URI; defaults to https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN: authorization-server origin; defaults to https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE: introspection by default, or jwks when the authorization service issues JSON Web Tokens (JWTs) suitable for local signature verification.
• MCP_OAUTH_CLIENT_ID and MCP_OAUTH_CLIENT_SECRET: no defaults; used as HTTP Basic credentials for Request for Comments (RFC) 7662 introspection.
• MCP_OAUTH_INTROSPECT_URL: defaults to https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: space-separated discovery scopes; defaults to didit:management didit:verification.

Authorization metadata overrides

• DIDIT_AUTH_ISSUER: defaults to MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL: OpenID Connect (OIDC) discovery document; defaults to the authorization origin plus /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL: JSON Web Key Set (JWKS) endpoint; defaults to https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL: defaults to the authorization origin plus /authorize.
• DIDIT_OIDC_TOKEN_URL: defaults to the authorization origin plus /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: defaults to the authorization origin plus /api/auth/oauth-register.

Use introspection for opaque access tokens. The server sends them to the configured introspection endpoint using MCP_OAUTH_CLIENT_ID and MCP_OAUTH_CLIENT_SECRET. Use jwks only when your authorization service is configured to issue signed JWT access tokens for this client; the server then validates signatures against DIDIT_JWKS_URL. Changing the verification mode does not create a different identity model: the validated principal remains a Didit user.

MCP clients can use Dynamic Client Registration (DCR) with the Didit Business Console during their authorization flow. That client registration is separate from the resource server's MCP_OAUTH_CLIENT_ID and MCP_OAUTH_CLIENT_SECRET, which authenticate introspection requests. Provision those server-side credentials through the appropriate Didit deployment channel rather than assuming a client registration can replace them.

Health checks and stateless scaling

The HTTP process exposes GET /healthz and returns JSON containing status, service, and version. The Docker image already checks it every 30 seconds after a 15-second startup period. You can use the same endpoint for Kubernetes readiness, an Application Load Balancer target group, or an external uptime probe.

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

The MCP route is stateless by design. For every authenticated POST, the process creates a fresh server and Streamable HTTP transport with session generation disabled, forwards the caller's validated credential through per-request context, completes the dispatch, and closes the transport. There is no in-memory session that a later request must find on the same replica.

Here, stateless describes the MCP transport and request lifecycle. Verification sessions, workflows, cases, and other business records still persist in Didit's upstream services.

As a result, horizontal replicas do not need sticky sessions. Any healthy instance can handle the next POST, and rolling deployments do not require session draining beyond ordinary in-flight request handling. Capacity planning should focus on request concurrency, downstream Didit API latency, and your normal timeout and retry policy.

Validate before exposing the service

• Confirm /healthz succeeds from the same network path as the load balancer.
• Confirm unauthenticated MCP requests receive an authorization challenge rather than tool output.
• Complete an OAuth 2.1 flow with Proof Key for Code Exchange (PKCE), then call didit_context_get to verify the expected organizations and applications are visible.
• Review the advanced MCP documentation before changing discovery endpoints or token verification.
• Use the Didit MCP developer page for the supported managed surface and current links.

If self-hosting is no longer a requirement, the managed endpoint removes the runtime and OAuth resource-server operations described above. Claude users can add it with the Didit connector deep link. Whether you run the process or Didit does, the core rule is identical: MCP operations authenticate as a Didit user, never as an application API key.