Hospedagem Própria do Servidor Didit MCP

Principais pontos

• O servidor Didit Model Context Protocol (MCP) é de código aberto sob a licença MIT. Você pode construí-lo a partir do repositório público do GitHub e executá-lo com Docker, Node.js ou um transporte stdio "headless".
• A auto-hospedagem altera onde o processo MCP é executado, não como ele alcança o Didit. Todo modo autentica como um usuário Didit com um token de acesso Bearer. Não há modo de chave de API de aplicativo para ferramentas MCP.
• O catálogo completo auto-hospedado contém 121 ferramentas. O endpoint Open Authorization (OAuth) hospedado expõe intencionalmente 115. Exemplos na fonte atual incluem didit_context_get, didit_session_create e didit_transaction_screen_wallet.
• O ponto de entrada HTTP é "stateless" e aceita tráfego MCP por meio de requisições POST. Um novo servidor e transporte são criados por requisição, portanto, um balanceador de carga não precisa de afinidade de sessão.
• Use /healthz para verificações de contêiner e balanceador de carga. Configure o URI de recurso público, a origem de autorização, o modo de verificação de token e os segredos explicitamente antes de expor o serviço.

O endpoint hospedado é conveniente, mas não é a escolha operacional certa para todas as equipes. Uma empresa pode precisar manter a integração dentro de sua própria fronteira de rede, controlar a imagem de tempo de execução, rotear o tráfego por uma camada de saída privada ou aplicar suas próprias políticas de observabilidade e gerenciamento de mudanças. O repositório Didit MCP suporta esse modelo de implantação sem criar uma superfície de produto separada.

Este guia se concentra apenas na operação do servidor. Para o catálogo e o comportamento da ferramenta, use a referência de ferramentas Didit MCP. Para a configuração do cliente contra o endpoint gerenciado, use o guia de instalação do Claude. As referências técnicas completas estão na visão geral do MCP e na documentação de autenticação.

Escolha o ponto de entrada HTTP ou stdio

O repositório constrói um catálogo de ferramentas compartilhadas com dois pontos de entrada. dist/http.js executa um servidor de recursos Express sobre HTTP "Streamable" "stateless". É a escolha correta para um serviço compartilhado acessado por vários clientes MCP, contêineres ou usuários. dist/index.js é executado sobre stdio e destina-se a um processo local "headless" iniciado por um cliente.

Ambos os pontos de entrada chamam a mesma lógica de despacho, e a versão 5 expõe apenas ferramentas MCP — não recursos ou prompts MCP. Ambos autenticam requisições "downstream" como um usuário Didit. A diferença é como essa credencial de usuário chega ao processo: o ponto de entrada HTTP recebe e valida o token Bearer OAuth do chamador; o ponto de entrada stdio lê um token Bearer de usuário de DIDIT_ACCESS_TOKEN.

Auto-hospedado não significa sem credenciais: o MCP ainda atua como um usuário Didit, e o Didit aplica a função e as permissões da organização desse usuário a cada chamada de ferramenta.

Construa e execute com Docker

O repositório inclui um Dockerfile multi-estágio baseado no Node 20. O estágio de construção instala dependências de desenvolvimento, compila TypeScript e remove pacotes de desenvolvimento. O estágio de produção é executado como o usuário node não-root e inclui uma verificação de saúde do contêiner.

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 o contêiner, substitua os padrões hospedados que identificam sua implantação. No mínimo, defina MCP_RESOURCE_URI para a origem pública através da qual os clientes alcançam este servidor de recursos e, em seguida, forneça as credenciais de cliente OAuth necessárias para a introspecção de token. Mantenha os segredos no gerenciador de segredos da sua plataforma de contêiner, em vez de "commitar" o arquivo .env preenchido.

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"

Termine o Transport Layer Security (TLS) em sua entrada ou balanceador de carga, encaminhe as requisições POST do MCP para a porta 3000 e preserve o cabeçalho Authorization. O MCP_RESOURCE_URI visível externamente deve corresponder à identidade do recurso anunciada aos clientes; não deixe o URI Didit gerenciado no lugar para uma origem pública diferente.

Construa e execute diretamente com Node.js

Se sua plataforma já gerencia um tempo de execução Node, use o mesmo ponto de entrada HTTP sem um contêiner. O pacote é privado e não é distribuído via npm, então clone o repositório em vez de tentar executar um pacote publicado.

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

O processo lê as mesmas variáveis de ambiente que o contêiner. Execute-o sob seu supervisor de processo, injete segredos através do ambiente de implantação e roteie apenas os endpoints necessários. As requisições MCP vão para POST /mcp. O serviço rejeita deliberadamente GET e DELETE nessa rota porque não mantém sessões MCP ou fluxos iniciados pelo servidor.

Node.js não carrega o arquivo .env do repositório automaticamente. Exporte os valores no shell, injete-os através do gerenciador de serviços ou use o suporte de arquivo de ambiente da sua plataforma antes de iniciar dist/http.js. Observe também que npm start inicia o ponto de entrada stdio; use node dist/http.js ou npm run start:http para HTTP.

Execute "headless" sobre stdio

Para um agente local, "build runner" ou processo isolado de cliente único, use o ponto de entrada stdio. Forneça um token de acesso de usuário através do ambiente e deixe o cliente MCP ser o proprietário do ciclo de vida do processo.

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

Este token é uma credencial Bearer de usuário, não uma credencial de aplicativo. Armazene-o como um segredo, mantenha-o fora do histórico de shell e logs e rotacione-o de acordo com sua política de acesso. Se uma implantação sempre opera em uma organização ou aplicativo, MCP_DEFAULT_ORG e MCP_DEFAULT_APP podem fornecer esse escopo padrão. Caso contrário, as ferramentas podem resolver o escopo a partir de argumentos explícitos ou do contexto da requisição autenticada.

Ainda não há modo de chave de API de aplicativo em stdio. Tanto o HTTP auto-hospedado quanto o stdio auto-hospedado chamam endpoints de console Didit com escopo de usuário, portanto, uma chave de aplicativo não pode substituir o token Bearer do usuário.

Configure a superfície completa do ambiente

O src/config.ts atual suporta as seguintes variáveis. A maioria das implantações deve manter os padrões de API e autorização do Didit de produção e substituir apenas a identidade do recurso, a configuração de verificação e os segredos necessários para sua topologia.

Variáveis compartilhadas e stdio

• DIDIT_ACCESS_TOKEN: token Bearer de usuário para o modo stdio "headless"; sem padrão.
• DIDIT_API_BASE_URL: base da API de verificação; o padrão é https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL: base da API de autenticação; o padrão é https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG e MCP_DEFAULT_APP: padrões opcionais de organização e aplicativo para implantações de locatário único.

Variáveis do servidor de recursos HTTP

• MCP_PORT: porta de escuta; o padrão é 3000.
• MCP_RESOURCE_URI: URI do servidor de recursos público; o padrão é https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN: origem do servidor de autorização; o padrão é https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE: introspection por padrão, ou jwks quando o serviço de autorização emite JSON Web Tokens (JWTs) adequados para verificação de assinatura local.
• MCP_OAUTH_CLIENT_ID e MCP_OAUTH_CLIENT_SECRET: sem padrões; usados como credenciais HTTP Basic para introspecção de Request for Comments (RFC) 7662.
• MCP_OAUTH_INTROSPECT_URL: o padrão é https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: escopos de descoberta separados por espaço; o padrão é didit:management didit:verification.

Sobrescritas de metadados de autorização

• DIDIT_AUTH_ISSUER: o padrão é MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL: documento de descoberta OpenID Connect (OIDC); o padrão é a origem de autorização mais /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL: endpoint JSON Web Key Set (JWKS); o padrão é https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL: o padrão é a origem de autorização mais /authorize.
• DIDIT_OIDC_TOKEN_URL: o padrão é a origem de autorização mais /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: o padrão é a origem de autorização mais /api/auth/oauth-register.

Use introspection para tokens de acesso opacos. O servidor os envia para o endpoint de introspecção configurado usando MCP_OAUTH_CLIENT_ID e MCP_OAUTH_CLIENT_SECRET. Use jwks apenas quando seu serviço de autorização estiver configurado para emitir tokens de acesso JWT assinados para este cliente; o servidor então valida as assinaturas contra DIDIT_JWKS_URL. Alterar o modo de verificação não cria um modelo de identidade diferente: o principal validado permanece um usuário Didit.

Os clientes MCP podem usar o Dynamic Client Registration (DCR) com o Didit Business Console durante seu fluxo de autorização. Esse registro de cliente é separado do MCP_OAUTH_CLIENT_ID e MCP_OAUTH_CLIENT_SECRET do servidor de recursos, que autenticam as requisições de introspecção. Provisione essas credenciais do lado do servidor através do canal de implantação Didit apropriado, em vez de assumir que um registro de cliente pode substituí-las.

Verificações de saúde e escalonamento "stateless"

O processo HTTP expõe GET /healthz e retorna JSON contendo status, service e version. A imagem Docker já o verifica a cada 30 segundos após um período de inicialização de 15 segundos. Você pode usar o mesmo endpoint para "readiness" do Kubernetes, um grupo de destino do Application Load Balancer ou uma sonda de "uptime" externa.

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

A rota MCP é "stateless" por design. Para cada POST autenticado, o processo cria um novo servidor e transporte HTTP "Streamable" com geração de sessão desabilitada, encaminha a credencial validada do chamador através do contexto por requisição, completa o despacho e fecha o transporte. Não há sessão em memória que uma requisição posterior deva encontrar na mesma réplica.

Aqui, "stateless" descreve o transporte MCP e o ciclo de vida da requisição. Sessões de verificação, fluxos de trabalho, casos e outros registros de negócios ainda persistem nos serviços "upstream" do Didit.

Como resultado, réplicas horizontais não precisam de sessões fixas. Qualquer instância saudável pode lidar com o próximo POST, e as implantações progressivas não exigem drenagem de sessão além do tratamento usual de requisições em andamento. O planejamento de capacidade deve se concentrar na concorrência de requisições, na latência da API Didit "downstream" e em sua política normal de tempo limite e repetição.

Valide antes de expor o serviço

• Confirme se /healthz é bem-sucedido a partir do mesmo caminho de rede que o balanceador de carga.
• Confirme se as requisições MCP não autenticadas recebem um desafio de autorização em vez da saída da ferramenta.
• Complete um fluxo OAuth 2.1 com Proof Key for Code Exchange (PKCE) e, em seguida, chame didit_context_get para verificar se as organizações e aplicativos esperados estão visíveis.
• Revise a documentação avançada do MCP antes de alterar os endpoints de descoberta ou a verificação de token.
• Use a página do desenvolvedor Didit MCP para a superfície gerenciada suportada e links atuais.

Se a auto-hospedagem não for mais um requisito, o endpoint gerenciado remove as operações de tempo de execução e servidor de recursos OAuth descritas acima. Os usuários do Claude podem adicioná-lo com o link direto do conector Didit. Quer você execute o processo ou o Didit o faça, a regra central é idêntica: as operações MCP autenticam como um usuário Didit, nunca como uma chave de API de aplicativo.