Despliegue del Servidor MCP de Didit: Guía de Autoalojamiento

Puntos clave

• El servidor del Protocolo de Contexto de Modelo (MCP) de Didit es de código abierto bajo la licencia MIT. Puedes construirlo desde el repositorio público de GitHub y ejecutarlo con Docker, Node.js o un transporte stdio sin interfaz gráfica.
• El autoalojamiento cambia dónde se ejecuta el proceso MCP, no cómo llega a Didit. Cada modo se autentica como un usuario de Didit con un token de acceso Bearer. No hay modo de clave API de aplicación para las herramientas MCP.
• El catálogo completo autoalojado contiene 121 herramientas. El endpoint de Autorización Abierta (OAuth) alojado expone intencionalmente 115. Ejemplos en la fuente actual incluyen didit_context_get, didit_session_create y didit_transaction_screen_wallet.
• El punto de entrada HTTP es sin estado y acepta tráfico MCP a través de solicitudes POST. Se crea un nuevo servidor y transporte por cada solicitud, por lo que un equilibrador de carga no necesita afinidad de sesión.
• Usa /healthz para las comprobaciones del contenedor y del equilibrador de carga. Configura el URI de recurso público, el origen de autorización, el modo de verificación de tokens y los secretos explícitamente antes de exponer el servicio.

El endpoint alojado es conveniente, pero no es la elección operativa correcta para todos los equipos. Una empresa puede necesitar mantener la integración dentro de su propio límite de red, controlar la imagen de tiempo de ejecución, enrutar el tráfico a través de una capa de salida privada o aplicar sus propias políticas de observabilidad y gestión de cambios. El repositorio Didit MCP admite ese modelo de implementación sin crear una superficie de producto separada.

Esta guía se centra únicamente en la operación del servidor. Para el catálogo y el comportamiento de las herramientas, utiliza la referencia de herramientas Didit MCP. Para la configuración del cliente contra el endpoint gestionado, utiliza la guía de instalación de Claude. Las referencias técnicas completas se encuentran en la descripción general de MCP y la documentación de autenticación.

Elige el punto de entrada HTTP o stdio

El repositorio construye un catálogo de herramientas compartido con dos puntos de entrada. dist/http.js ejecuta un servidor de recursos Express sobre HTTP Streamable sin estado. Es la elección correcta para un servicio compartido al que acceden varios clientes MCP, contenedores o usuarios. dist/index.js se ejecuta sobre stdio y está destinado a un proceso local sin interfaz gráfica lanzado por un solo cliente.

Ambos puntos de entrada llaman a la misma lógica de despacho, y la versión 5 expone solo herramientas MCP, no recursos o indicaciones MCP. Ambos autentican las solicitudes posteriores como un usuario de Didit. La diferencia radica en cómo esa credencial de usuario llega al proceso: el punto de entrada HTTP recibe y valida el token Bearer OAuth del llamante; el punto de entrada stdio lee un token Bearer de usuario de DIDIT_ACCESS_TOKEN.

Autoalojado no significa sin credenciales: el MCP sigue actuando como un usuario de Didit, y Didit aplica el rol y los permisos de la organización de ese usuario a cada llamada de herramienta.

Construir y ejecutar con Docker

El repositorio incluye un Dockerfile multi-etapa basado en Node 20. La etapa de construcción instala las dependencias de desarrollo, compila TypeScript y elimina los paquetes de desarrollo. La etapa de producción se ejecuta como el usuario node no root e incluye una comprobación de estado del contenedor.

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

Antes de iniciar el contenedor, reemplaza los valores predeterminados alojados que identifican tu despliegue. Como mínimo, establece MCP_RESOURCE_URI al origen público a través del cual los clientes acceden a este servidor de recursos, luego proporciona las credenciales de cliente OAuth necesarias para la introspección de tokens. Mantén los secretos en el gestor de secretos de tu plataforma de contenedores en lugar de confirmar el archivo .env poblado.

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"

Termina la Seguridad de la Capa de Transporte (TLS) en tu entrada o equilibrador de carga, reenvía las solicitudes POST de MCP al puerto 3000 y conserva el encabezado Authorization. El MCP_RESOURCE_URI visible externamente debe coincidir con la identidad del recurso anunciada a los clientes; no dejes el URI de Didit gestionado en su lugar para un origen público diferente.

Construir y ejecutar directamente con Node.js

Si tu plataforma ya gestiona un tiempo de ejecución de Node, utiliza el mismo punto de entrada HTTP sin un contenedor. El paquete es privado y no se distribuye a través de npm, así que clona el repositorio en lugar de intentar ejecutar un paquete publicado.

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

El proceso lee las mismas variables de entorno que el contenedor. Ejecútalo bajo tu supervisor de procesos, inyecta secretos a través del entorno de despliegue y enruta solo los endpoints requeridos. Las solicitudes MCP van a POST /mcp. El servicio rechaza deliberadamente GET y DELETE en esa ruta porque no mantiene sesiones MCP ni flujos iniciados por el servidor.

Node.js no carga automáticamente el archivo .env del repositorio. Exporta los valores en el shell, inyéctalos a través del gestor de servicios o utiliza el soporte de archivos de entorno de tu plataforma antes de iniciar dist/http.js. Ten en cuenta también que npm start lanza el punto de entrada stdio; usa node dist/http.js o npm run start:http para HTTP.

Ejecutar sin interfaz gráfica a través de stdio

Para un agente local, un ejecutor de compilación o un proceso aislado de un solo cliente, utiliza el punto de entrada stdio. Suministra un token de acceso de usuario a través del entorno y deja que el cliente MCP sea el propietario del ciclo de vida del proceso.

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

Este token es una credencial Bearer de usuario, no una credencial de aplicación. Almacénalo como un secreto, mantenlo fuera del historial de shell y los registros, y rótalo de acuerdo con tu política de acceso. Si un despliegue siempre opera en una organización o aplicación, MCP_DEFAULT_ORG y MCP_DEFAULT_APP pueden proporcionar ese alcance predeterminado. De lo contrario, las herramientas pueden resolver el alcance a partir de argumentos explícitos o el contexto de la solicitud autenticada.

Todavía no hay un modo de clave API de aplicación en stdio. Tanto HTTP autoalojado como stdio autoalojado llaman a los endpoints de la consola de Didit con alcance de usuario, por lo que una clave de aplicación no puede sustituir al token Bearer de usuario.

Configurar la superficie de entorno completa

El src/config.ts actual admite las siguientes variables. La mayoría de los despliegues deben mantener los valores predeterminados de la API de Didit y de autorización de producción y anular solo la identidad del recurso, la configuración de verificación y los secretos necesarios para su topología.

Variables compartidas y de stdio

• DIDIT_ACCESS_TOKEN: token Bearer de usuario para el modo stdio sin interfaz gráfica; sin valor predeterminado.
• DIDIT_API_BASE_URL: base de la API de verificación; por defecto es https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL: base de la API de autenticación; por defecto es https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG y MCP_DEFAULT_APP: valores predeterminados opcionales de organización y aplicación para despliegues de un solo inquilino.

Variables del servidor de recursos HTTP

• MCP_PORT: puerto de escucha; por defecto es 3000.
• MCP_RESOURCE_URI: URI público del servidor de recursos; por defecto es https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN: origen del servidor de autorización; por defecto es https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE: introspection por defecto, o jwks cuando el servicio de autorización emite JSON Web Tokens (JWTs) adecuados para la verificación de firma local.
• MCP_OAUTH_CLIENT_ID y MCP_OAUTH_CLIENT_SECRET: sin valores predeterminados; utilizados como credenciales HTTP Basic para la introspección de Request for Comments (RFC) 7662.
• MCP_OAUTH_INTROSPECT_URL: por defecto es https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: ámbitos de descubrimiento separados por espacios; por defecto es didit:management didit:verification.

Anulaciones de metadatos de autorización

• DIDIT_AUTH_ISSUER: por defecto es MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL: documento de descubrimiento de OpenID Connect (OIDC); por defecto es el origen de autorización más /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL: endpoint de JSON Web Key Set (JWKS); por defecto es https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL: por defecto es el origen de autorización más /authorize.
• DIDIT_OIDC_TOKEN_URL: por defecto es el origen de autorización más /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: por defecto es el origen de autorización más /api/auth/oauth-register.

Usa introspection para tokens de acceso opacos. El servidor los envía al endpoint de introspección configurado usando MCP_OAUTH_CLIENT_ID y MCP_OAUTH_CLIENT_SECRET. Usa jwks solo cuando tu servicio de autorización esté configurado para emitir tokens de acceso JWT firmados para este cliente; el servidor luego valida las firmas contra DIDIT_JWKS_URL. Cambiar el modo de verificación no crea un modelo de identidad diferente: el principal validado sigue siendo un usuario de Didit.

Los clientes MCP pueden usar el Registro Dinámico de Clientes (DCR) con la Consola de Negocios de Didit durante su flujo de autorización. Ese registro de cliente es independiente de MCP_OAUTH_CLIENT_ID y MCP_OAUTH_CLIENT_SECRET del servidor de recursos, que autentican las solicitudes de introspección. Proporciona esas credenciales del lado del servidor a través del canal de despliegue de Didit apropiado en lugar de asumir que un registro de cliente puede reemplazarlas.

Comprobaciones de estado y escalado sin estado

El proceso HTTP expone GET /healthz y devuelve JSON que contiene status, service y version. La imagen de Docker ya lo comprueba cada 30 segundos después de un período de inicio de 15 segundos. Puedes usar el mismo endpoint para la preparación de Kubernetes, un grupo de destino de Application Load Balancer o una sonda de tiempo de actividad externa.

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

La ruta MCP es sin estado por diseño. Para cada POST autenticado, el proceso crea un nuevo servidor y un transporte HTTP Streamable con la generación de sesiones deshabilitada, reenvía la credencial validada del llamante a través del contexto por solicitud, completa el despacho y cierra el transporte. No hay una sesión en memoria que una solicitud posterior deba encontrar en la misma réplica.

Aquí, sin estado describe el transporte MCP y el ciclo de vida de la solicitud. Las sesiones de verificación, los flujos de trabajo, los casos y otros registros comerciales aún persisten en los servicios upstream de Didit.

Como resultado, las réplicas horizontales no necesitan sesiones pegajosas. Cualquier instancia saludable puede manejar la siguiente POST, y los despliegues continuos no requieren el vaciado de sesiones más allá del manejo ordinario de solicitudes en curso. La planificación de la capacidad debe centrarse en la concurrencia de solicitudes, la latencia de la API de Didit aguas abajo y tu política normal de tiempo de espera y reintentos.

Validar antes de exponer el servicio

• Confirma que /healthz se ejecuta correctamente desde la misma ruta de red que el equilibrador de carga.
• Confirma que las solicitudes MCP no autenticadas reciben un desafío de autorización en lugar de la salida de la herramienta.
• Completa un flujo de OAuth 2.1 con Proof Key for Code Exchange (PKCE), luego llama a didit_context_get para verificar que las organizaciones y aplicaciones esperadas sean visibles.
• Revisa la documentación avanzada de MCP antes de cambiar los endpoints de descubrimiento o la verificación de tokens.
• Utiliza la página de desarrolladores de Didit MCP para la superficie gestionada compatible y los enlaces actuales.

Si el autoalojamiento ya no es un requisito, el endpoint gestionado elimina las operaciones de tiempo de ejecución y del servidor de recursos OAuth descritas anteriormente. Los usuarios de Claude pueden agregarlo con el enlace profundo del conector Didit. Ya sea que ejecutes el proceso o lo haga Didit, la regla principal es idéntica: las operaciones MCP se autentican como un usuario de Didit, nunca como una clave API de aplicación.