MCP BuscaProcessos

O servidor MCP da BuscaProcessos expõe, como ferramentas estruturadas, todas as operações públicas descritas no OpenAPI. A autenticação, o saldo, os descontos, a cobrança, a paginação e os contratos assíncronos são os mesmos da API REST.

O catálogo não é mantido manualmente: cada operationId público do OpenAPI gera uma ferramenta MCP. Quando uma nova operação é publicada no contrato, ela passa a integrar o MCP na mesma atualização. Um teste de cobertura impede que uma operação pública fique sem ferramenta correspondente.

Endpoint

https://api.buscaprocessos.app.br/mcp

O transporte é Streamable HTTP. O servidor aceita a API Key em x-api-key ou Authorization: Bearer; recomendamos x-api-key nos clientes que permitem configurar headers.

Configuração

{
  "mcpServers": {
    "BuscaProcessos": {
      "url": "https://api.buscaprocessos.app.br/mcp",
      "headers": {
        "x-api-key": "bp_live_SUA_CHAVE"
      }
    }
  }
}

Substitua bp_live_SUA_CHAVE pela API Key criada no Console BuscaProcessos. Guarde a chave no cofre de segredos do cliente e não a publique em código, prints, prompts ou repositórios.

Cobertura automática das operações

Cada operação REST possui uma ferramenta com o prefixo api_ e o operationId convertido para snake_case.

REST	Ferramenta MCP
GET /v1/processos	api_listar_processos_por_documento
GET /v1/processos/cnj/{cnj}	api_consultar_processo_por_cnj
POST /v1/monitoramentos/processos	api_criar_monitoramento_de_processo
DELETE /v1/monitoramentos/processos/{id}	api_remover_monitoramento_de_processo

Os parâmetros de path e query aparecem no primeiro nível dos argumentos da ferramenta. Operações com JSON recebem o campo body, validado pelo mesmo schema publicado no OpenAPI.

O MCP cobre:

• saúde, saldo e respostas assíncronas;
• busca geral, busca por termo, CPF/CNPJ, OAB e resumos;
• capa, movimentações, diários, documentos e resumo por IA;
• criação, consulta, atualização e remoção de monitoramentos;
• radares de novos processos e qualificação de resultados;
• intimações, publicações e sistemas dos tribunais.

Atalhos compatíveis

Os nomes anteriores continuam disponíveis para não quebrar clientes já configurados:

Ferramenta	Finalidade
consultar_saldo	Consultar o saldo da conta
consultar_precos	Listar preços-base vigentes
resumir_advogado_por_oab	Consultar o resumo da OAB
buscar_processos_por_oab	Listar processos vinculados a uma OAB
buscar_processos_por_documento	Listar processos de um CPF ou CNPJ
consultar_capa_processo	Consultar a capa pelo CNJ
consultar_movimentacoes_processo	Consultar movimentações pelo CNJ

No atalho buscar_processos_por_documento, o filtro aceita até cinco tribunais. Com tribunais, o preço-base é R$ 0,25 por tribunal informado que retornar ao menos um processo; tribunais sem resultado e páginas seguintes da mesma busca não geram nova cobrança da listagem. Sem o filtro, aplica-se a cobrança por quantidade prevista na tabela vigente.

Confirmações de segurança

O MCP separa dois tipos de autorização:

• confirmar_cobranca=true: necessário em operações que podem consumir créditos;
• confirmar_operacao=true: necessário em POST, PUT, PATCH e DELETE, pois criam, alteram ou removem dados.

Se uma operação tiver os dois efeitos, os dois campos serão exigidos. Antes da confirmação, a ferramenta não chama a API e não consome créditos.

Operações novas são consideradas potencialmente pagas por segurança até serem classificadas explicitamente como gratuitas. Descontos negociados continuam sendo aplicados pela própria API.

A resposta informa, quando aplicável:

• creditsCharged: valor efetivamente debitado;
• creditsRemaining: saldo restante;
• requestId: identificador para suporte e auditoria;
• searchLogId: identificador do registro de consulta.

Operações assíncronas e paginação

Quando a API responder HTTP 202, use Location ou data.statusUrl e respeite Retry-After ou pollAfterMs. A consulta de status usa a mesma API Key e não deve reiniciar nem cobrar novamente a operação original.

Na paginação, siga data.links.next.href, cursor e demais marcadores devolvidos pela API. As páginas seguintes da mesma pesquisa não devem gerar nova cobrança da listagem.

Eventos e webhooks

O MCP é request-response: ele cria e consulta monitoramentos, mas não mantém um receptor permanente para eventos em tempo real. Para receber eventos novos, configure webhook_url nas operações compatíveis.

O contrato de callback, headers de assinatura e schema de evento são publicados no OpenAPI. O MCP também oferece estes recursos legíveis pelo cliente:

Recurso	Conteúdo
buscaprocessos://openapi	Contrato OpenAPI completo
buscaprocessos://openapi/operacoes	Relação entre operações REST e ferramentas MCP
buscaprocessos://openapi/eventos-webhook	Callback e schema vigentes dos eventos

Assim, eventos passados existentes em endpoints de histórico podem ser consultados pelas respectivas ferramentas; eventos futuros em tempo real continuam sendo entregues por webhook.

Exemplo de uso

Consulte meu saldo e informe o custo para buscar os processos do CPF 00000000000 no TJRJ. Não execute sem minha confirmação.

Para criar um monitoramento:

Explique o custo e o efeito de monitorar diariamente o CNJ 0000000-00.2026.8.26.0000. Aguarde minha autorização antes de criar.

Erros comuns

HTTP/código	Significado	Como resolver
401 API_KEY_REQUIRED	Chave ausente	Configure x-api-key ou Bearer
401 INVALID_API_KEY	Chave inválida ou revogada	Gere ou copie uma chave ativa no Console
403 ACCOUNT_INACTIVE	Conta inativa	Contate o suporte
403 INSUFFICIENT_CREDITS	Saldo insuficiente	Faça uma recarga
422	Parâmetro ou body inválido	Revise os argumentos descritos na ferramenta
429	Limite de requisições atingido	Aguarde e tente novamente com backoff

Segurança

• a API Key é validada em todas as requisições MCP;
• a chave nunca aparece nas respostas das ferramentas;
• o executor aceita somente caminhos públicos /v1 da própria origem BuscaProcessos;
• não existe ferramenta genérica para chamar URLs arbitrárias;
• mutações e cobranças exigem confirmação explícita;
• as mesmas regras de conta, LGPD, rate limit e créditos da API REST continuam válidas.