Testando ferramentas MCP com credenciais falsas que falham com segurança

Testar ferramentas MCP com segurança exige mais do que substituir um token de produção por uma string chamada TEST_TOKEN. Uma ferramenta pode analisar o valor falso, retornar uma mensagem amigável de sucesso e ainda falhar na primeira vez que um agente encontrar um limite de permissão real, uma aprovação negada, um provedor lento ou uma gravação parcialmente concluída.

O ambiente de testes precisa permitir que você prove duas coisas ao mesmo tempo: a ferramenta envia a solicitação esperada e não consegue causar uma consequência real na produção quando algo dá errado. Contas descartáveis e credenciais falsas resolvem partes diferentes desse trabalho. Trate-as como controles separados.

Credenciais falsas testam a análise, não a autoridade

Uma credencial falsa prova apenas que a ferramenta lida corretamente com um valor no formato de uma credencial. Ela não prova que o provedor aceita a credencial, que ela tem os escopos esperados ou que um valor revogado falha de maneira adequada.

Essa diferença fica confusa porque muitas equipes chamam todo segredo que não é de produção de segredo falso. Há três coisas materialmente diferentes:

• Uma string sintética existe apenas em um stub local. Ela não pode autenticar em lugar nenhum.
• Uma credencial de teste autentica em um provedor real, mas apenas dentro de um tenant ou projeto descartável.
• Uma credencial de produção restrita pode autenticar na produção, mesmo que seu escopo pareça pequeno.

A primeira opção pertence aos testes unitários e de contrato. A segunda pertence aos testes de integração. A terceira não deve fazer parte de uma suíte automatizada de testes de agentes. Uma credencial que consegue ler o registro de um cliente de produção já ultrapassou o limite que você pretendia proteger.

Faça os valores falsos se parecerem com o formato que seu código realmente recebe. Se um cliente de API rejeita tokens sem prefixo ou com comprimento mínimo, use um valor sintético que passe nessa validação local. Não copie um token real e altere um caractere. As pessoas colam fixtures em rastreadores de problemas, transcrições de terminal e conversas. Um segredo quase real traz todo o risco de tratamento sem oferecer benefício de teste.

Um fixture útil informa a autoridade que ele não possui. Por exemplo, stub_token_no_network diz mais do que token123. Uma referência de credencial de teste como billing_test_writer indica que um armazenamento de segredos, e não o agente, resolve o valor real. Mantenha a referência estável e troque a credencial de teste subjacente quando necessário.

Não confunda um mock bem-sucedido com autorização. Quando um stub retorna 200, ele aceitou qualquer contrato que você programou nele. Isso é uma evidência útil sobre a construção da sua própria solicitação. Não diz nada sobre o modelo de escopos do provedor.

Separe entrada inválida, rejeição e falha operacional

Um agente precisa de orientações diferentes para um argumento incorreto, uma ação negada e uma dependência com problemas. Se sua ferramenta MCP transforma os três casos em request failed, o agente tentará novamente ações que deveria interromper e abandonará ações que poderia corrigir.

Use um vocabulário pequeno de resultados e preserve-o no resultado da ferramenta. Eu uso cinco classes:

• Erro de validação: o agente forneceu um argumento inválido ou incompleto. Ele pode corrigir a chamada.
• Falha de autenticação: a credencial está ausente, expirada, malformada ou revogada. Repetir a mesma chamada não ajudará.
• Rejeição de autorização: a identidade foi autenticada, mas não tem permissão, ou uma pessoa negou uma aprovação. O agente não deve tentar contornar o limite.
• Conflito: a solicitação era válida, mas não pode ser aplicada ao estado atual do recurso. Talvez o agente precise buscar o estado atual primeiro.
• Falha operacional: timeout, falha de conexão, limite de taxa ou falha do provedor. Uma nova tentativa pode fazer sentido se for seguro repetir a ação.

O HTTP define as partes conhecidas dessa separação. A RFC 9110 descreve 401 Unauthorized como um desafio de autenticação, apesar do nome historicamente confuso, e 403 Forbidden como uma recusa em atender à solicitação. Seu provedor pode usar esses códigos de forma imperfeita, portanto teste também o corpo e os códigos de erro documentados. Não defina o comportamento do agente apenas pelo código de status.

O resultado de uma ferramenta do Model Context Protocol aceita um sinalizador isError junto do conteúdo. Use-o quando a chamada da ferramenta falhar, mas coloque a categoria acionável no texto ou no conteúdo estruturado esperado pelo seu cliente. Um erro JSON RPC no nível de transporte e um erro no nível da ferramenta também são diferentes. Reserve erros JSON RPC para solicitações de protocolo malformadas ou métodos indisponíveis. Retorne um resultado normal de tools/call com isError: true quando a ferramenta tiver sido executada e a ação upstream tiver falhado ou sido rejeitada.

Esse formato de resposta dá ao agente algo concreto para fazer:

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "authorization_rejected: identity billing_test_writer cannot create invoices in tenant test-acme. Request a role change or stop."
      }
    ],
    "isError": true
  }
}

Não inclua o bearer token, o cabeçalho de autorização, a solicitação upstream completa nem o erro bruto do provedor nesse resultado. Mensagens de erro fazem parte da janela de contexto do agente, o que significa que podem ser retidas por sistemas que você não controla. O erro precisa ter detalhes suficientes para orientar o comportamento, não para servir como registro forense completo.

Contas descartáveis precisam de um limite rígido

Uma conta descartável só é segura quando não há caminho até recursos de produção. Um endereço de e-mail separado e o rótulo test não criam esse limite.

Comece pela unidade de isolamento mais forte oferecida pelo provedor. Pode ser uma organização, tenant, projeto de nuvem, banco de dados ou instância hospedada separada. Coloque a conta de teste dentro dessa unidade e confirme que ela não pode mudar para uma unidade de produção por meio de um identificador, uma função compartilhada ou um valor de configuração padrão.

Depois, dê à conta as permissões necessárias para o teste previsto, e nada além disso. Se uma ferramenta cria faturas nos testes, sua identidade de teste precisa de permissão para criar e listar faturas de teste. Ela não precisa de permissões de exportação, acesso de administrador nem acesso a uma configuração de pagamento compartilhada. O acesso amplo em testes é popular porque reduz o tempo de configuração. Também esconde de quais permissões a ferramenta realmente precisa.

Use um marcador explícito de execução de teste em cada recurso criado pela suíte. Coloque-o em um campo de metadados compatível, na descrição, em uma tag ou no nome. Um marcador torna a limpeza mais segura e facilita reconhecer artefatos de teste esquecidos. Não apague tudo que estiver em um tenant de teste. Outro desenvolvedor pode estar reproduzindo um bug ali.

Uma configuração mínima pode ser assim:

run_id: mcp-it-20250308-7f3c
account: [email protected]
allowed_tenant: test-acme
resource_prefix: mcp-it-20250308-7f3c-
cleanup_after_minutes: 90

A configuração evita uma falha comum e cara: o executor de testes aponta para o tenant errado porque uma variável de ambiente do shell de um desenvolvedor prevalece sobre a configuração versionada. O código de configuração deve buscar a identidade do tenant atual antes de criar qualquer coisa e compará-la com allowed_tenant. Se forem diferentes, pare antes da primeira gravação.

Descartável não significa anônimo nem sem responsável. Defina um proprietário, registre como a credencial é emitida e torne a expiração intencional. Uma identidade de teste esquecida ainda é uma identidade com acesso.

Crie contratos em torno de solicitações observáveis

Um bom teste de contrato verifica a solicitação enviada pela ferramenta, o resultado retornado e as informações que ela se recusa a expor. Ele não apenas confirma que uma função foi chamada.

Coloque um stub HTTP local diante do cliente e faça com que ele inspecione método, caminho, cabeçalhos, parâmetros de consulta e corpo. O stub deve rejeitar campos inesperados. Mocks permissivos treinam a ferramenta a enviar argumentos acidentais até que um provedor real os rejeite.

Para uma ferramenta create_invoice, um teste focado pode fazer esta chamada:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "create_invoice",
    "arguments": {
      "tenant": "test-acme",
      "customer_id": "cus_mcp_it_7f3c",
      "amount_cents": 500,
      "currency": "USD"
    }
  }
}

O stub deve esperar POST /v1/invoices, confirmar que o cabeçalho de autorização contém o valor sintético de teste e confirmar que a solicitação inclui o marcador de execução. Ele pode retornar um identificador fixo como inv_mcp_it_001. O resultado MCP deve expor o identificador e o status da fatura, mas nunca repetir o cabeçalho de autorização.

Escreva pelo menos uma asserção negativa de contrato para cada campo sensível da solicitação. Envie um campo authorization, base_url, account_id ou tenant fornecido pelo chamador se o seu schema puder aceitar algum deles. Confirme que a ferramenta rejeita ou ignora valores que poderiam redirecionar uma ação para outra conta. Muitos vazamentos de credenciais começam como uma saída aparentemente inofensiva para um endpoint personalizado.

Teste a serialização da solicitação nos bytes que importam. Um provedor pode distinguir campos omitidos de null, strings vazias de valores ausentes e números de strings numéricas. Agentes produzem formatos de argumentos inesperados, especialmente quando a descrição da ferramenta não informa as unidades. Seu schema deve dizer amount_cents, e não amount, se o provedor espera unidades menores.

Os testes de contrato também são o lugar para impor higiene nos logs. Capture o evento de log estruturado e confirme que ele contém uma referência de credencial ou um marcador redigido, nunca o próprio segredo sintético. Um segredo falso vira um problema real de exposição quando os engenheiros se acostumam a imprimi-lo em todo lugar.

Teste permissões como uma matriz, não como um caminho feliz

Uma única identidade de teste autorizada não mostra se a ferramenta lida corretamente com permissões. Você precisa de várias identidades com direitos deliberadamente diferentes e de um conjunto de casos que nomeie o resultado esperado.

Mantenha a matriz pequena o suficiente para ser mantida. Para uma ferramenta de gravação, estes casos normalmente valem a pena:

Essa matriz detecta um defeito comum: a ferramenta verifica se existe um token, mas nunca verifica qual tenant o token realmente representa. O caminho feliz passa porque o gravador tem acesso amplo. A falha aparece quando um agente recebe um identificador de tenant em uma tarefa e o cliente o aceita sem vinculá-lo à credencial selecionada.

Execute cada caso da matriz contra o provedor descartável real quando puder. As semânticas do provedor relacionadas a funções herdadas, escopos padrão e revogação atrasada costumam diferir da documentação. Mantenha os casos isolados. Se um teste eleva uma função que outro espera que esteja ausente, execuções paralelas criam falhas que parecem bugs de autorização.

Não fabrique respostas proibidas apenas em um stub e considere a suíte concluída. Um stub confirma que seu mapeador de erros reconhece um 403. A identidade de teste real confirma que o processo de emissão da credencial, a configuração do provedor e o roteamento da ferramenta produzem uma rejeição verdadeira.

Há uma exceção útil: testar respostas do provedor que você não consegue acionar de forma confiável, como JSON malformado ou um tipo de conteúdo inválido. Um stub cuida desses casos. O objetivo não é pureza. É saber que evidência cada teste fornece.

As gravações precisam de planos de limpeza antes do código de teste

Para cada ferramenta que altera estado, decida como o teste removerá ou neutralizará esse estado antes de escrever o teste de sucesso. Se você não consegue descrever a limpeza, escolha outro destino ou outra operação.

Prefira operações que criem registros dentro de um projeto de teste de curta duração. Evite chamadas de teste que enviem e-mails, cobrem um cartão, troquem um segredo compartilhado, acionem uma implantação ou contatem terceiros reais. Um sandbox do provedor ainda pode enviar webhooks para um endpoint configurado anos atrás. Verifique os efeitos ao redor, não apenas o rótulo da API.

Use um marcador de execução exclusivo e faça a limpeza em um bloco finally ou equivalente. A limpeza precisa tolerar um recurso que nunca foi criado, um recurso criado duas vezes após uma nova tentativa e uma conta configurada parcialmente. Uma limpeza idempotente economiza tempo quando um teste falha no meio do provisionamento.

Uma falha que vale a pena testar é esta. A ferramenta envia uma solicitação de criação. O provedor cria o registro, mas encerra a conexão antes de retornar a resposta. O agente vê uma falha operacional e tenta novamente. Sem um valor de idempotência, a nova tentativa cria uma duplicata. Sem um marcador de execução, a limpeza não consegue encontrar os dois registros com segurança.

Dê à solicitação de criação um valor de idempotência derivado do identificador de execução e da ação lógica, não da tentativa de transporte. A primeira tentativa e a nova tentativa devem usar o mesmo valor. Depois, teste o caso de resposta perdida com um stub que registre a primeira solicitação, feche a conexão e retorne sucesso ao receber novamente o mesmo valor de idempotência. Confirme que existe apenas um registro no lado do provedor.

Se o provedor não oferecer idempotência, faça a ferramenta consultar uma referência externa exclusiva antes de tentar novamente uma gravação. Essa abordagem pode sofrer condições de corrida com concorrência, portanto documente o risco restante. Não repita silenciosamente movimentações financeiras ou gravações irreversíveis porque um cliente HTTP genérico considera POST passível de nova tentativa.

Timeouts e limites de taxa revelam comportamentos ruins do agente

Uma ferramenta que lida corretamente com sucesso e 403 ainda pode causar danos quando sua dependência fica lenta. Agentes tendem a tentar novamente porque estão tentando concluir a tarefa. Sua ferramenta precisa fornecer uma resposta limitada e verdadeira.

Teste um timeout de conexão antes que qualquer solicitação chegue ao servidor, um timeout de resposta depois que o servidor recebe a solicitação e uma resposta 429 do provedor. Esses casos são diferentes. O primeiro geralmente significa que nenhum efeito colateral ocorreu. O segundo pode significar que o servidor concluiu a gravação. Um 429 pode incluir uma instrução de nova tentativa, mas só a use se o provedor documentar o campo e sua ferramenta preservar o significado dele.

Defina timeouts curtos nos testes para que a suíte continue utilizável, mas não substitua os timeouts de produção por valores de teste no código. Injete um relógio ou uma configuração de transporte. Um timeout de dois segundos fixado no código é uma conveniência de teste que se transformará em uma indisponibilidade quando alguém fizer a implantação.

Suas asserções devem cobrir o comportamento voltado ao agente, além do cliente HTTP. Para um limite de taxa, retorne uma falha operacional que identifique o provedor e diga se é permitido tentar novamente após uma espera. Para um timeout de resposta depois de uma gravação, diga que o resultado é desconhecido e instrua o chamador a consultar a operação pelo valor de idempotência ou pela referência externa. Chamar esse caso de simples falha convida a gravações duplicadas.

Não teste novas tentativas verificando apenas uma contagem. Registre se a tentativa reutilizou o valor de idempotência, se esperou quando deveria e se parou no limite configurado. Um loop de novas tentativas que termina depois de algum tempo ainda pode criar uma explosão de chamadas, esgotar um tenant de teste pequeno e esconder o defeito real.

A rejeição de aprovação deve deixar o destino intacto

Se uma pessoa pode aprovar ações de agentes, teste o caminho de rejeição contra um endpoint em que um efeito colateral seja evidente. Uma tela dizendo «negado» não prova que a camada de execução parou.

Configure um destino descartável com um contador, um registro marcado ou uma lista de eventos de teste somente de anexação. Inicie o processo do agente, faça a chamada da ferramenta e negue a sessão ou a chamada. Depois, consulte o destino diretamente com uma identidade de observador de teste separada. A contagem esperada não muda.

Esse teste detecta um bug de ordenação ruim: a ferramenta inicia a solicitação upstream e depois pede aprovação enquanto espera a resposta. Esse fluxo pode parecer correto em uma demonstração se o provedor for lento. Ele viola o objetivo da aprovação. A decisão de autorização deve acontecer antes que o despachante de ações abra a conexão de rede ou inicie um auxiliar SSH.

Teste um processo de agente novo separadamente de uma segunda chamada no mesmo processo. Essas são promessas de segurança distintas em sistemas que concedem autorização por execução. Teste também um processo cuja identidade de assinatura seja diferente da esperada. O pedido de aprovação deve mostrar informações de origem suficientes para que a pessoa consiga distinguir o agente pretendido de um processo local arbitrário.

Em um fluxo local no Mac, o Sallyport mantém as credenciais de API e SSH em seu cofre criptografado e pode exigir uma aprovação para cada nova execução de agente ou para cada uso de uma credencial selecionada. Trate esses controles como itens a serem testados contra endpoints descartáveis, não como motivo para ignorar os testes de permissões upstream.

Testes SSH precisam de um destino que possa ser descartado

O SSH acrescenta modos de falha que exemplos HTTP escondem: verificação do host, aspas de comandos, herança de ambiente, comportamento do shell remoto e arquivos deixados para trás depois de uma conexão interrompida. Nunca aponte testes automatizados de SSH de agentes para a estação de trabalho de um desenvolvedor ou um host de administração compartilhado.

Crie uma máquina de teste controlada ou uma máquina virtual de curta duração com uma conta exclusiva. Dê a essa conta um diretório pessoal sem dados úteis, um conjunto restrito de comandos quando possível e nenhuma credencial capaz de alcançar outros sistemas. Use uma chave SSH de teste exclusiva e descarte-a quando o ambiente expirar.

Exercite argumentos de comandos que quebram uma construção ingênua do shell. Teste espaços, aspas, caracteres de nova linha, caminhos que começam com hífen e dados que parecem sintaxe de shell. A ferramenta deve passar argumentos ao comando remoto sem concatenar valores fornecidos pelo usuário em uma string de shell. Se a interface remota necessária aceitar apenas texto de shell, restrinja a gramática de comandos permitida e rejeite tudo que estiver fora dela.

Um teste seguro pode pedir ao destino que crie um arquivo com o nome do marcador de execução e depois leia exatamente esse arquivo. Um teste de rejeição pode solicitar um caminho fora do diretório permitido para a conta de teste e esperar que o destino o negue. Um teste operacional pode encerrar a conexão SSH depois que o comando começar e então verificar se o processo remoto continuou.

Colete o status de saída, a saída padrão limitada e o erro padrão limitado. Não retorne uma quantidade ilimitada de saída de comandos a um agente. Saídas grandes consomem contexto, e a saída de comandos costuma conter valores de configuração que nunca deveriam deixar o host.

As evidências de auditoria devem ligar a chamada do agente ao efeito colateral

Quando um teste de agente falha, você precisa responder se a ferramenta fez a chamada, se o provedor a recebeu e se a limpeza a removeu. Uma pilha de texto do console não responde a essas perguntas de maneira confiável.

Dê a cada execução de teste um identificador e carregue-o pela solicitação MCP, pelo log da ferramenta, pelos metadados do provedor e pelo log de limpeza. Não coloque credenciais nesse identificador. Um registro de evidência útil inclui o nome da ferramenta, a categoria da ação, a referência da credencial, o tenant de destino, o identificador de correlação da solicitação, a categoria do resultado e o identificador do recurso retornado.

Mantenha os registros de sessões dos agentes separados dos registros de ações. Uma sessão informa qual processo fez uma execução e quando ela foi revogada. Um registro de ação informa qual chamada externa ocorreu. Unir os dois por meio de um identificador de correlação torna um teste de rejeição auditável: você pode mostrar que o agente tentou uma ação, que a autorização a negou e que não existe um registro correspondente de ação externa.

A evidência contra adulteração importa quando você usa os resultados dos testes para revisar um novo limite de uma ferramenta. O Sallyport projeta seus registros de sessões e atividades a partir de um log de auditoria criptografado e encadeado por hash, e sp audit verify pode verificar essa cadeia offline sem uma chave do cofre. Isso não substitui os logs do provedor, mas oferece aos testes locais uma forma de detectar um histórico de ações alterado.

Não trate a saída de auditoria como um depósito de segredos. Registre referências de credenciais e atributos redigidos e valide essas regras nos testes. A trilha de auditoria deve ajudar a reconstruir uma ação sem se tornar o lugar mais fácil para roubar o acesso que a permitiu.

Um candidato a lançamento conquista o acesso à produção lentamente

Uma ferramenta deve avançar por limites cada vez mais realistas: stubs sintéticos locais, um provedor descartável real, identidades negadas e expiradas, injeção de falhas e um teste de aprovação humana se o fluxo usar um. Pular diretamente para a produção porque o sandbox é diferente é como as equipes descobrem seu comportamento de segurança sob pressão.

Mantenha uma suíte curta de lançamento que rode a cada alteração e uma suíte mais profunda que provisione recursos descartáveis com menos frequência. A suíte curta deve cobrir o schema da ferramenta, a construção da solicitação, a redação de dados e falhas representativas. A suíte profunda deve cobrir escopos reais, limpeza do ciclo de vida, revogação e isolamento do destino.

Antes de permitir uma nova ação na produção, examine as evidências de uma chamada deliberadamente negada e de um timeout de gravação deliberadamente ambíguo. Esses casos mostram se a ferramenta respeita um limite e se diz a verdade ao agente quando o provedor pode ter agido. Caminhos de sucesso são fáceis de preparar. É nos caminhos de recusa e incerteza que o acesso à produção se torna controlado ou imprudente.