Alojamento Próprio do Servidor Didit MCP: Guia Completo

Principais pontos

• O servidor Didit Model Context Protocol (MCP) é de código aberto sob a licença MIT. Pode construí-lo a partir do repositório público do GitHub e executá-lo com Docker, Node.js, ou um transporte stdio "headless".
• O alojamento próprio altera onde o processo MCP é executado, não como ele chega à Didit. Cada modo autentica-se como um utilizador Didit com um "Bearer access token". Não existe um modo de chave API de aplicação para as ferramentas MCP.
• O catálogo completo de alojamento próprio contém 121 ferramentas. O "endpoint" OAuth (Open Authorization) alojado 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 através de pedidos POST. Um novo servidor e transporte são criados por pedido, por isso um "load balancer" não necessita de afinidade de sessão.
• Use /healthz para verificações de contentores e "load balancer". Configure o URI do recurso público, a origem da autorização, o modo de verificação de "tokens" e os segredos explicitamente antes de expor o serviço.

O "endpoint" alojado é conveniente, mas não é a escolha operacional certa para todas as equipas. Uma empresa pode precisar de manter a integração dentro dos seus próprios limites de rede, controlar a imagem de tempo de execução, encaminhar o tráfego através de uma camada de saída privada, ou aplicar as suas próprias políticas de observabilidade e gestão de alterações. O repositório Didit MCP suporta esse modelo de implementação sem criar uma superfície de produto separada.

Este guia foca-se apenas na operação do servidor. Para o catálogo e comportamento das ferramentas, use a referência das ferramentas Didit MCP. Para a configuração do cliente contra o "endpoint" gerido, 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 partilhado 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 partilhado alcançado por vários clientes MCP, contentores ou utilizadores. 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 MCP ou "prompts". Ambos autenticam pedidos "downstream" como um utilizador Didit. A diferença é como essa credencial de utilizador chega ao processo: o ponto de entrada HTTP recebe e valida o "Bearer token" OAuth do chamador; o ponto de entrada stdio lê um "Bearer token" de utilizador de DIDIT_ACCESS_TOKEN.

"Self-hosted" não significa sem credenciais: o MCP ainda age como um utilizador Didit, e a Didit aplica a função e permissões da organização desse utilizador a cada chamada de ferramenta.

Construir e executar com Docker

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

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 contentor, substitua os padrões alojados que identificam a sua implementação. No mínimo, defina MCP_RESOURCE_URI para a origem pública através da qual os clientes chegam a este servidor de recursos, e depois forneça as credenciais de cliente OAuth necessárias para a introspeção de "tokens". Mantenha os segredos no gestor de segredos da sua plataforma de contentores em vez de submeter o ficheiro .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=substituir-com-client-id
MCP_OAUTH_CLIENT_SECRET=substituir-com-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"

Termine o Transport Layer Security (TLS) no seu "ingress" ou "load balancer", encaminhe os pedidos POST 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 gerido no lugar para uma origem pública diferente.

Construir e executar diretamente com Node.js

Se a sua plataforma já gere um tempo de execução Node, use o mesmo ponto de entrada HTTP sem um contentor. O pacote é privado e não é distribuído através do npm, por isso 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 contentor. Execute-o sob o seu supervisor de processos, injete segredos através do ambiente de implementação e encaminhe apenas os "endpoints" necessários. Os pedidos 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 "streams" iniciados pelo servidor.

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

Executar "headless" sobre stdio

Para um agente local, "build runner" ou processo isolado de cliente único, use o ponto de entrada stdio. Forneça um "access token" de utilizador através do ambiente e deixe o cliente MCP gerir o ciclo de vida do processo.

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

Este "token" é uma credencial "Bearer" de utilizador, não uma credencial de aplicação. Armazene-o como um segredo, mantenha-o fora do histórico da "shell" e registos, e faça a sua rotação de acordo com a sua política de acesso. Se uma implementação operar sempre numa organização ou aplicação, MCP_DEFAULT_ORG e MCP_DEFAULT_APP podem fornecer esse âmbito padrão. Caso contrário, as ferramentas podem resolver o âmbito a partir de argumentos explícitos ou do contexto de pedido autenticado.

Ainda não há modo de chave API de aplicação em stdio. Tanto o HTTP "self-hosted" quanto o stdio "self-hosted" chamam "endpoints" da consola Didit com âmbito de utilizador, por isso uma chave de aplicação não pode substituir o "Bearer token" de utilizador.

Configurar a superfície completa do ambiente

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

Variáveis partilhadas e stdio

• DIDIT_ACCESS_TOKEN: "Bearer token" de utilizador 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 aplicação para implementações de "single-tenant".

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 introspeção do Request for Comments (RFC) 7662.
• MCP_OAUTH_INTROSPECT_URL: o padrão é https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: âmbitos de descoberta separados por espaço; o padrão é didit:management didit:verification.

Sobrescrições 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 da 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 da autorização mais /authorize.
• DIDIT_OIDC_TOKEN_URL: o padrão é a origem da autorização mais /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: o padrão é a origem da autorização mais /api/auth/oauth-register.

Use introspection para "access tokens" opacos. O servidor envia-os para o "endpoint" de introspeção configurado usando MCP_OAUTH_CLIENT_ID e MCP_OAUTH_CLIENT_SECRET. Use jwks apenas quando o seu serviço de autorização estiver configurado para emitir "access tokens" 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 utilizador Didit.

Os clientes MCP podem usar Dynamic Client Registration (DCR) com a Consola de Negócios Didit durante o seu fluxo de autorização. Esse registo de cliente é separado do MCP_OAUTH_CLIENT_ID e MCP_OAUTH_CLIENT_SECRET do servidor de recursos, que autenticam os pedidos de introspeção. Forneça essas credenciais do lado do servidor através do canal de implementação Didit apropriado, em vez de assumir que um registo de cliente pode substituí-las.

Verificações de saúde e escalabilidade "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. Pode usar o mesmo "endpoint" para prontidão do Kubernetes, um grupo de destino do Application Load Balancer ou uma sonda de tempo de atividade 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 a geração de sessão desativada, encaminha a credencial validada do chamador através do contexto por pedido, completa o despacho e fecha o transporte. Não há sessão em memória que um pedido posterior deva encontrar na mesma réplica.

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

Como resultado, as réplicas horizontais não precisam de sessões fixas. Qualquer instância saudável pode lidar com o próximo POST, e as implementações contínuas não exigem o esgotamento da sessão além do tratamento normal de pedidos em curso. O planeamento da capacidade deve focar-se na concorrência de pedidos, latência da API Didit "downstream" e na sua política normal de "timeout" e repetição.

Validar antes de expor o serviço

• Confirme que /healthz é bem-sucedido a partir do mesmo caminho de rede que o "load balancer".
• Confirme que os pedidos MCP não autenticados recebem um desafio de autorização em vez de saída de ferramenta.
• Conclua um fluxo OAuth 2.1 com Proof Key for Code Exchange (PKCE), depois chame didit_context_get para verificar se as organizações e aplicações esperadas estão visíveis.
• Reveja a documentação avançada do MCP antes de alterar os "endpoints" de descoberta ou a verificação de "tokens".
• Use a página de programador Didit MCP para a superfície gerida suportada e os links atuais.

Se o alojamento próprio deixar de ser um requisito, o "endpoint" gerido remove as operações de tempo de execução e de servidor de recursos OAuth descritas acima. Os utilizadores do Claude podem adicioná-lo com o link direto do conector Didit. Quer seja você a executar o processo ou a Didit, a regra central é idêntica: as operações MCP autenticam-se como um utilizador Didit, nunca como uma chave API de aplicação.