Conectar o servidor MCP a qualquer cliente: stdio e transporte HTTP

A maior parte do material sobre o servidor MCP da SignDocs mostra a configuração de um cliente específico, o que dá a impressão de que cada cliente exige um tratamento próprio. Não exige. O servidor é um pacote npm executado sobre stdio — o transporte padrão do protocolo —, e isso significa que qualquer cliente MCP compatível conecta com os mesmos três ingredientes: um comando, seus argumentos e algumas variáveis de ambiente. Este guia mostra a receita genérica, como traduzi-la para o formato de configuração que o seu cliente usar, e o segundo modo de conexão — um transporte HTTP que permite uma implantação atender vários agentes ao mesmo tempo.

Por que a receita é a mesma em todo lugar

O servidor MCP da SignDocs é um servidor stdio distribuído como pacote npm — o arranjo mais comum do ecossistema. O cliente inicia um processo local e conversa com ele pela entrada e saída padrão; o protocolo cuida do resto.

A consequência prática é boa: não existe integração específica por cliente a manter. Qualquer cliente MCP que saiba iniciar um processo e falar stdio conecta com os mesmos ingredientes. O que muda de um para outro é apenas onde essa configuração é escrita — um arquivo JSON, uma linha de comando, um formulário na interface.

Os três ingredientes

As credenciais saem do painel de API da sua conta. As variáveis opcionais são poucas: além do ambiente, dá para sobrescrever a URL base e o conjunto de escopos, mas nenhuma das duas é necessária num uso normal.

A forma mais comum: um bloco JSON

A maioria dos clientes de desktop usa um arquivo de configuração com esta estrutura:

É este o formato do Claude Desktop, e é o mesmo esqueleto que a maior parte dos clientes compatíveis adota. Se o seu cliente usa outro nome para a chave raiz ou pede a configuração numa tela, os campos a preencher continuam sendo os mesmos três.

A forma de linha de comando

Clientes de terminal costumam registrar o servidor por comando, com as variáveis passadas por parâmetro:

Repare que é a mesma receita: tudo depois de -- é o comando e os argumentos, e cada -e é uma variável de ambiente. Traduzir entre os dois formatos é mecânico.

Traduzindo para um cliente qualquer

Se o seu cliente MCP não aparece em nenhum exemplo, procure onde ele pede estas três coisas — os nomes variam, o conteúdo não:

• "command" / "executable" / "binary" → npx
• "args" / "arguments" / "parameters" → -y @signdocs-brasil/mcp-server
• "env" / "environment" / "variables" → as três variáveis

Dois detalhes que resolvem a maior parte dos problemas de primeira conexão:

O npx precisa estar no caminho do processo que o cliente inicia. Aplicações de desktop nem sempre herdam o mesmo PATH do seu terminal — se o cliente reclama que não encontrou o comando, apontar o caminho absoluto do executável resolve.

Instalar globalmente é uma alternativa válida. Com npm install -g @signdocs-brasil/mcp-server, o pacote deixa de ser resolvido a cada início; o comportamento é idêntico, muda apenas quem resolve o pacote e quando.

O segundo modo: transporte HTTP

O stdio pressupõe um processo local por usuário, com as credenciais no arquivo de configuração da máquina. Isso é adequado para uma pessoa trabalhando no próprio computador e inadequado quando o agente roda num servidor, ou quando muitos agentes precisam do mesmo servidor.

Para esse caso as mesmas ferramentas são servidas sobre HTTP, de modo que uma implantação atenda vários agentes — cada um autenticando por sessão com a própria credencial, sem segredo compartilhado embutido no servidor.

O endpoint é POST /mcp, e a autenticação acontece na requisição de inicialização, por cabeçalho. São aceitos três formatos, para acomodar clientes com capacidades diferentes:

O ambiente também é escolhido por cabeçalho, sessão a sessão — o que permite que o mesmo servidor atenda um agente em homologação e outro em produção ao mesmo tempo.

Duas propriedades úteis para quem opera: o servidor se comporta como um resource server OAuth 2.0, respondendo a uma inicialização não autenticada com 401 e o cabeçalho de desafio apropriado, e a validação do token continua sendo feita pela API — o servidor MCP não é uma autoridade de autenticação paralela. Há ainda uma rota de saúde sem autenticação, útil para verificação de disponibilidade.

Escolhendo entre os dois modos

No modo stdio, vale lembrar que o arquivo de configuração passa a conter um segredo — e merece o mesmo cuidado que qualquer outro arquivo nessa condição: fora do repositório, fora de captura de tela, e rotacionado quando alguém com acesso à máquina sai. O procedimento está em rotação de credenciais.

Depois de conectar

Confirme a conexão pedindo algo somente leitura — a situação da conta, ou a lista de documentos recentes. Se responder, a credencial e o ambiente estão corretos, e você evita descobrir um erro de configuração no meio de um envio.

Antes de deixar o agente enviar de verdade, vale conhecer como a ordem dos signatários é decidida quando o pedido vem em linguagem natural, em ordem de assinatura em linguagem natural — e revisar a configuração de aprovação automática do seu cliente, mantendo as ferramentas que criam ou cancelam fora de qualquer lista de execução sem confirmação.

Para instalar a partir do registro oficial em vez de escrever a configuração à mão, veja instalar pelo registro oficial de MCP. E para o que existe atrás dessas ferramentas, a visão geral da API de assinatura digital.

Perguntas Frequentes