Com allotjar el servidor MCP de Didit en el teu propi entorn (CA)

Aspectes clau

• El servidor del Protocol de Context del Model (MCP) de Didit és de codi obert sota la llicència MIT. Pots construir-lo des del repositori públic de GitHub i executar-lo amb Docker, Node.js o un transport stdio sense capçalera.
• L'autoallotjament canvia on s'executa el procés MCP, no com arriba a Didit. Cada mode s'autentica com a usuari de Didit amb un testimoni d'accés Bearer. No hi ha mode de clau d'API d'aplicació per a les eines MCP.
• El catàleg complet autoallotjat conté 121 eines. El punt final d'Autorització Oberta (OAuth) allotjat exposa intencionadament 115. Alguns exemples en la font actual inclouen didit_context_get, didit_session_create i didit_transaction_screen_wallet.
• El punt d'entrada HTTP no té estat i accepta tràfic MCP mitjançant sol·licituds POST. Es crea un servidor i un transport nous per cada sol·licitud, de manera que un balancejador de càrrega no necessita afinitat de sessió.
• Utilitza /healthz per a comprovacions de contenidors i balancejadors de càrrega. Configura explícitament l'URI públic del recurs, l'origen de l'autorització, el mode de verificació del testimoni i els secrets abans d'exposar el servei.

El punt final allotjat és convenient, però no és l'elecció operativa correcta per a tots els equips. Una empresa pot necessitar mantenir la integració dins dels seus propis límits de xarxa, controlar la imatge d'execució, encaminar el tràfic a través d'una capa d'eixida privada o aplicar les seves pròpies polítiques d'observabilitat i gestió de canvis. El repositori Didit MCP admet aquest model de desplegament sense crear una superfície de producte separada.

Aquesta guia se centra només en l'operació del servidor. Per al catàleg i el comportament de les eines, utilitza la referència d'eines Didit MCP. Per a la configuració del client contra el punt final gestionat, utilitza la guia d'instal·lació de Claude. Les referències tècniques completes es troben a la visió general de MCP i la documentació d'autenticació.

Tria el punt d'entrada HTTP o stdio

El repositori construeix un catàleg d'eines compartit amb dos punts d'entrada. dist/http.js executa un servidor de recursos Express sobre HTTP transmissible sense estat. És l'opció correcta per a un servei compartit al qual accedeixen diversos clients MCP, contenidors o usuaris. dist/index.js s'executa sobre stdio i està pensat per a un procés local sense capçalera iniciat per un client.

Ambdós punts d'entrada criden la mateixa lògica de despatx, i la versió 5 exposa només eines MCP, no recursos ni avisos MCP. Ambdós autentiquen les sol·licituds posteriors com a usuari de Didit. La diferència és com aquesta credencial d'usuari arriba al procés: el punt d'entrada HTTP rep i valida el testimoni Bearer OAuth de la persona que truca; el punt d'entrada stdio llegeix un testimoni Bearer d'usuari de DIDIT_ACCESS_TOKEN.

Autoallotjar no significa sense credencials: l'MCP encara actua com a usuari de Didit, i Didit aplica el rol i els permisos d'organització d'aquest usuari a cada crida de l'eina.

Construir i executar amb Docker

El repositori inclou un Dockerfile multi-etapa basat en Node 20. L'etapa de construcció instal·la les dependències de desenvolupament, compila TypeScript i elimina els paquets de desenvolupament. L'etapa de producció s'executa com a usuari node no root i inclou una comprovació de salut del contenidor.

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

Abans d'iniciar el contenidor, reemplaça els valors predeterminats allotjats que identifiquen el teu desplegament. Com a mínim, configura MCP_RESOURCE_URI a l'origen públic a través del qual els clients accedeixen a aquest servidor de recursos, i després proporciona les credencials de client OAuth necessàries per a la introspecció del testimoni. Mantén els secrets al gestor de secrets de la teva plataforma de contenidors en lloc de confirmar el fitxer .env completat.

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 Transport Layer Security (TLS) al teu ingress o balancejador de càrrega, reenvia les sol·licituds POST de MCP al port 3000 i conserva la capçalera Authorization. L'MCP_RESOURCE_URI visible externament ha de coincidir amb la identitat del recurs anunciada als clients; no deixis l'URI gestionat de Didit al seu lloc per a un origen públic diferent.

Construir i executar directament amb Node.js

Si la teva plataforma ja gestiona un temps d'execució de Node, utilitza el mateix punt d'entrada HTTP sense un contenidor. El paquet és privat i no es distribueix a través de npm, així que clona el repositori en lloc d'intentar executar un paquet publicat.

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

El procés llegeix les mateixes variables d'entorn que el contenidor. Executa'l sota el teu supervisor de processos, injecta secrets a través de l'entorn de desplegament i encamina només els punts finals requerits. Les sol·licituds MCP van a POST /mcp. El servei rebutja deliberadament GET i DELETE en aquesta ruta perquè no manté sessions MCP ni fluxos iniciats pel servidor.

Node.js no carrega automàticament el fitxer .env del repositori. Exporta els valors a l'intèrpret d'ordres, injecta'ls a través del gestor de serveis o utilitza el suport de fitxers d'entorn de la teva plataforma abans d'iniciar dist/http.js. També tingues en compte que npm start inicia el punt d'entrada stdio; utilitza node dist/http.js o npm run start:http per a HTTP.

Executar sense capçalera sobre stdio

Per a un agent local, un executor de compilació o un procés aïllat d'un sol client, utilitza el punt d'entrada stdio. Proporciona un testimoni d'accés d'usuari a través de l'entorn i deixa que el client MCP sigui el propietari del cicle de vida del procés.

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

Aquest testimoni és una credencial Bearer d'usuari, no una credencial d'aplicació. Guarda'l com a secret, mantén-lo fora de l'historial i els registres de l'intèrpret d'ordres, i rota'l segons la teva política d'accés. Si un desplegament sempre opera en una organització o aplicació, MCP_DEFAULT_ORG i MCP_DEFAULT_APP poden proporcionar aquest àmbit predeterminat. En cas contrari, les eines poden resoldre l'àmbit a partir d'arguments explícits o del context de la sol·licitud autenticada.

Encara no hi ha cap mode de clau d'API d'aplicació a stdio. Tant HTTP autoallotjat com stdio autoallotjat criden punts finals de la consola de Didit amb àmbit d'usuari, de manera que una clau d'aplicació no pot substituir el testimoni Bearer d'usuari.

Configura la superfície completa de l'entorn

L'actual src/config.ts admet les següents variables. La majoria dels desplegaments haurien de mantenir els valors predeterminats de l'API de Didit de producció i d'autorització i només substituir la identitat del recurs, la configuració de verificació i els secrets necessaris per a la seva topologia.

Variables compartides i stdio

• DIDIT_ACCESS_TOKEN: testimoni Bearer d'usuari per al mode stdio sense capçalera; sense valor predeterminat.
• DIDIT_API_BASE_URL: base de l'API de verificació; per defecte a https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL: base de l'API d'autenticació; per defecte a https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG i MCP_DEFAULT_APP: valors predeterminats opcionals d'organització i aplicació per a desplegaments de llogater únic.

Variables del servidor de recursos HTTP

• MCP_PORT: port d'escolta; per defecte a 3000.
• MCP_RESOURCE_URI: URI públic del servidor de recursos; per defecte a https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN: origen del servidor d'autorització; per defecte a https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE: introspection per defecte, o jwks quan el servei d'autorització emet JSON Web Tokens (JWTs) adequats per a la verificació de signatura local.
• MCP_OAUTH_CLIENT_ID i MCP_OAUTH_CLIENT_SECRET: sense valors predeterminats; utilitzats com a credencials HTTP Bàsiques per a la introspecció de la Request for Comments (RFC) 7662.
• MCP_OAUTH_INTROSPECT_URL: per defecte a https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: àmbits de descoberta separats per espais; per defecte a didit:management didit:verification.

Sobrescripcions de metadades d'autorització

• DIDIT_AUTH_ISSUER: per defecte a MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL: document de descoberta d'OpenID Connect (OIDC); per defecte a l'origen de l'autorització més /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL: punt final de JSON Web Key Set (JWKS); per defecte a https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL: per defecte a l'origen de l'autorització més /authorize.
• DIDIT_OIDC_TOKEN_URL: per defecte a l'origen de l'autorització més /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: per defecte a l'origen de l'autorització més /api/auth/oauth-register.

Utilitza introspection per a testimonis d'accés opacs. El servidor els envia al punt final d'introspecció configurat utilitzant MCP_OAUTH_CLIENT_ID i MCP_OAUTH_CLIENT_SECRET. Utilitza jwks només quan el teu servei d'autorització estigui configurat per emetre testimonis d'accés JWT signats per a aquest client; el servidor llavors valida les signatures contra DIDIT_JWKS_URL. Canviar el mode de verificació no crea un model d'identitat diferent: el principal validat segueix sent un usuari de Didit.

Els clients MCP poden utilitzar el Registre Dinàmic de Clients (DCR) amb la Consola de Negocis de Didit durant el seu flux d'autorització. Aquest registre de client és independent de les credencials MCP_OAUTH_CLIENT_ID i MCP_OAUTH_CLIENT_SECRET del servidor de recursos, que autentiquen les sol·licituds d'introspecció. Proporciona aquestes credencials del costat del servidor a través del canal de desplegament de Didit adequat en lloc d'assumir que un registre de client pot substituir-les.

Comprovacions de salut i escalat sense estat

El procés HTTP exposa GET /healthz i retorna JSON que conté status, service i version. La imatge de Docker ja el comprova cada 30 segons després d'un període d'inici de 15 segons. Pots utilitzar el mateix punt final per a la preparació de Kubernetes, un grup de destinació de l'Application Load Balancer o una sonda de temps d'activitat externa.

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

La ruta MCP és sense estat per disseny. Per a cada POST autenticat, el procés crea un servidor nou i un transport HTTP transmissible amb la generació de sessions desactivada, reenvia la credencial validada de la persona que truca a través del context per sol·licitud, completa el despatx i tanca el transport. No hi ha cap sessió en memòria que una sol·licitud posterior hagi de trobar a la mateixa rèplica.

Aquí, sense estat descriu el transport MCP i el cicle de vida de la sol·licitud. Les sessions de verificació, els fluxos de treball, els casos i altres registres de negoci encara persisteixen als serveis ascendents de Didit.

Com a resultat, les rèpliques horitzontals no necessiten sessions enganxoses. Qualsevol instància sana pot gestionar la següent POST, i els desplegaments continus no requereixen l'esgotament de sessions més enllà de la gestió ordinària de sol·licituds en curs. La planificació de la capacitat s'ha de centrar en la concurrència de sol·licituds, la latència de l'API de Didit posterior i la vostra política normal de temps d'espera i reintents.

Valida abans d'exposar el servei

• Confirma que /healthz s'executa correctament des de la mateixa ruta de xarxa que el balancejador de càrrega.
• Confirma que les sol·licituds MCP no autenticades reben un desafiament d'autorització en lloc de la sortida de l'eina.
• Completa un flux OAuth 2.1 amb Proof Key for Code Exchange (PKCE) i, a continuació, truca a didit_context_get per verificar que les organitzacions i aplicacions esperades són visibles.
• Revisa la documentació avançada de MCP abans de canviar els punts finals de descoberta o la verificació del testimoni.
• Utilitza la pàgina de desenvolupadors de Didit MCP per a la superfície gestionada admesa i els enllaços actuals.

Si l'autoallotjament ja no és un requisit, el punt final gestionat elimina les operacions del servidor de recursos de temps d'execució i OAuth descrites anteriorment. Els usuaris de Claude poden afegir-lo amb l'enllaç profund del connector Didit. Tant si executes el procés com si ho fa Didit, la regla bàsica és idèntica: les operacions MCP s'autentiquen com a usuari de Didit, mai com a clau d'API d'aplicació.