JSON-RPC no MCP

O que é JSON-RPC, em termos simples?

JSON-RPC é um protocolo leve de chamada de procedimento remoto. Em vez de acessar endereços diferentes para cada ação, como acontece em muitas APIs, o cliente envia uma mensagem dizendo qual função quer executar e com quais dados. O servidor executa e devolve o resultado em outra mensagem.

A sigla RPC vem de Remote Procedure Call, ou chamada de procedimento remoto. A parte JSON indica que todas as mensagens são escritas no formato JSON, que é texto simples, legível por pessoas e fácil de processar por qualquer linguagem de programação. O MCP usa a versão 2.0 desse protocolo.

Por que o MCP usa JSON-RPC?

O MCP precisa que agentes de IA de fornecedores diferentes conversem com servidores de ferramentas diferentes sem combinar tudo do zero a cada integração. O JSON-RPC resolve isso porque define uma estrutura fixa para pedidos, respostas e erros, e qualquer lado que siga a especificação consegue entender o outro.

Outra vantagem é que o JSON-RPC funciona nos dois sentidos. Tanto o cliente quanto o servidor podem enviar mensagens, o que permite ao servidor avisar o agente sobre mudanças, como uma nova ferramenta disponível, sem esperar ser perguntado.

Como é uma mensagem JSON-RPC no MCP?

Existem três tipos de mensagem. A requisição (request) tem os campos jsonrpc, com o valor 2.0, id, que identifica o pedido, method, com o nome da ação, e params, com os dados necessários. A resposta (response) repete o mesmo id e traz um campo result, quando deu certo, ou um campo error, quando algo falhou.

O terceiro tipo é a notificação (notification), uma mensagem sem id. Ela serve apenas para avisar algo e não espera resposta, como o aviso de que a inicialização da conexão foi concluída.

Os erros seguem códigos padronizados. Por exemplo, -32601 indica que o método pedido não existe e -32602 indica parâmetros inválidos. Além do código, a mensagem de erro traz um texto explicativo e, opcionalmente, dados extras.

Como funciona na prática em uma consulta fiscal?

Primeiro, o agente envia uma requisição initialize para combinar a versão do protocolo e os recursos que cada lado suporta. Depois, envia tools/list para descobrir quais ferramentas o servidor oferece, como consultar o status de uma NF-e ou baixar o XML de uma NFS-e.

Quando o usuário pede algo, o agente envia tools/call informando o nome da ferramenta e os argumentos, por exemplo a chave de acesso da nota. O servidor verifica se aquela credencial tem permissão para a ação, executa e devolve o resultado na resposta com o mesmo id. Em servidores fiscais, cada chamada pode ser registrada para auditoria.

Qual a diferença entre JSON-RPC e uma API REST?

Em uma API REST, cada recurso tem um endereço próprio e a ação é indicada pelo método HTTP, como GET para consultar ou POST para criar. No JSON-RPC, a ação vem escrita dentro da própria mensagem, no campo method, e o endereço de envio costuma ser sempre o mesmo.

Na prática, os dois podem conviver. Um servidor MCP fiscal pode receber chamadas JSON-RPC do agente e, por trás, acionar uma API REST de emissão. O JSON-RPC organiza a conversa com o agente, enquanto a API REST continua sendo usada por sistemas tradicionais, como ERPs.

Por onde as mensagens JSON-RPC trafegam no MCP?

O MCP separa o formato da mensagem do meio de transporte. As mesmas mensagens JSON-RPC podem trafegar pela entrada e saída padrão (stdio), quando o servidor roda na mesma máquina do agente, ou por HTTP, quando o servidor está na internet.

Em servidores remotos, como os que dão acesso a documentos fiscais, o transporte por HTTP normalmente é protegido por HTTPS e exige autenticação, como um token. Assim, o conteúdo da mensagem segue o padrão JSON-RPC, enquanto a segurança fica a cargo da camada de transporte e das permissões do servidor.

Exemplos de JSON-RPC no MCP

• Um agente de IA envia uma requisição com method tools/call, o nome de uma ferramenta de consulta e a chave de acesso de uma NF-e nos parâmetros; o servidor responde com o mesmo id e o status de autorização da nota.
• Ao conectar-se a um servidor MCP fiscal, o assistente envia initialize e, em seguida, tools/list, recebendo a lista de ações disponíveis, como consultar rejeições ou baixar o XML de uma NFS-e.
• O agente tenta chamar uma ferramenta de cancelamento sem informar a justificativa obrigatória e recebe uma resposta com error de código -32602, indicando parâmetros inválidos.
• Uma equipe de desenvolvimento analisa os logs de um servidor MCP e usa o campo id de cada mensagem JSON-RPC para relacionar cada pedido feito pelo agente à sua respectiva resposta.