# JSON-RPC no MCP > JSON-RPC no MCP é o formato de mensagens que o Model Context Protocol usa para a comunicação entre um agente de inteligência artificial e um servidor de ferramentas. Cada pedido, resposta ou aviso é um pequeno objeto JSON com campos padronizados, o que permite ao agente listar ferramentas, chamar ações e receber resultados de forma previsível. **Também conhecido como:** JSON-RPC 2.0 no MCP, Mensagens JSON-RPC do Model Context Protocol, Protocolo de mensagens do MCP, JSON-RPC in MCP **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** J ## 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. ## Perguntas frequentes ### Preciso conhecer JSON-RPC para usar um servidor MCP? Normalmente não. Os clientes de IA compatíveis com MCP montam e interpretam as mensagens JSON-RPC automaticamente. Conhecer o formato ajuda quando você desenvolve um servidor próprio, depura erros ou analisa logs de integração. ### O campo id é obrigatório? É obrigatório em requisições, porque é ele que liga o pedido à resposta correta. Notificações não têm id, já que não esperam resposta. No MCP, o id não pode ser nulo. ### JSON-RPC substitui a API REST de emissão fiscal? Não. O JSON-RPC é o idioma da conversa entre o agente de IA e o servidor MCP. A API REST continua sendo o caminho usual para sistemas como ERPs e plataformas de venda emitirem documentos fiscais. ### JSON-RPC é seguro para dados fiscais? O JSON-RPC define apenas o formato das mensagens. A segurança depende do transporte, como HTTPS, da autenticação por token e das permissões configuradas no servidor, que limitam quais ações cada agente pode executar. ## Termos relacionados - [Conota MCP](https://conota.dev/glossario/conota-mcp.md) - [MCP fiscal](https://conota.dev/glossario/mcp-fiscal.md) - [JSON](https://conota.dev/glossario/json.md) - [REST](https://conota.dev/glossario/rest.md) - [Permissão de acesso à API](https://conota.dev/glossario/permissao-de-acesso-a-api.md) - [Trilha de auditoria fiscal](https://conota.dev/glossario/trilha-de-auditoria-fiscal.md) --- Fonte: [JSON-RPC no MCP](https://conota.dev/glossario/json-rpc-no-mcp/) · Atualizado em 2026-10-22