Como adicionar Parallel Search MCP a um agente: busca sem chave, leitura web e limites de custo

É possível conectar o Parallel Search MCP sem manter um mecanismo de busca próprio nem solicitar uma API Key de busca. A Parallel oferece o endpoint Streamable HTTP https://search.parallel.ai/mcp, que expõe duas ferramentas ao agente: web_search e web_fetch.

Salvar a configuração não prova que a integração está funcionando. A verificação útil exige status de conexão, descoberta das duas ferramentas, evento real de tool call na conversa e URLs de origem que possam ser abertas. Os fatos abaixo foram conferidos em páginas oficiais abertas em 11 de outubro de 2026; seus logs e páginas de cobrança continuam sendo a evidência final.

Escolha o endpoint e o modo de autenticação

Objetivo	Endpoint	Autenticação	Uso indicado
Confirmar busca e leitura	https://search.parallel.ai/mcp	Nenhuma	Exploração leve com limites anônimos menores
Usar créditos da conta e limites maiores	https://search.parallel.ai/mcp	Bearer API Key	Carga recorrente ou de produção
Deixar o cliente controlar o login no navegador	https://search.parallel.ai/mcp-oauth	OAuth ou Bearer API Key	Evitar uma chave fixa em configuração compartilhada

O endpoint padrão /mcp não anuncia OAuth, então um cliente compatível pode se conectar anonimamente sem abrir o navegador. Já /mcp-oauth exige autenticação e devolve 401 a solicitações anônimas. A ausência de uma tela de login em /mcp não é falha; 401 em /mcp-oauth normalmente indica que a autorização não foi concluída.

Separe cliente, ferramenta web e provedor do modelo

Uma única resposta pode passar por três conexões independentes:

1. O cliente do agente gerencia conversa, permissões e seleção de ferramentas.
2. O Parallel Search MCP executa web_search e web_fetch.
3. O provedor do modelo faz o raciocínio e contabiliza tokens de entrada, saída e resultados de ferramentas.

Adicionar MCP não substitui o Base URL do modelo. Trocar o provedor de modelo também não adiciona busca web. Ao investigar um problema, faça três perguntas distintas: o cliente conectou ao MCP, a ferramenta foi realmente chamada e qual provedor cobrou a chamada do modelo?

Claude Code: comece pelo endpoint anônimo

Execute no projeto em que você usa o Claude Code:

claude mcp add --transport http "Parallel-Search-MCP" https://search.parallel.ai/mcp
claude mcp get "Parallel-Search-MCP"
claude mcp list

Por padrão, o Claude Code salva o servidor no escopo local. Adicione --scope user apenas quando quiser disponibilidade em todos os projetos. Em um .mcp.json compartilhado, revise o arquivo e nunca inclua um bearer token fixo.

Dentro do Claude Code, abra o painel:

/mcp

A mensagem Added confirma que a configuração foi gravada; o status Connected confirma que o cliente atual alcança o servidor. Para OAuth, use este endereço no lugar do padrão:

https://search.parallel.ai/mcp-oauth

Conclua a autorização em /mcp. Não misture a análise de erros de /mcp e /mcp-oauth.

Codex CLI: anônimo, bearer por variável ou OAuth

Configuração anônima:

codex mcp add parallel-search --url https://search.parallel.ai/mcp
codex mcp list

Para limites vinculados a uma conta, armazene PARALLEL_API_KEY no sistema operacional ou em um gerenciador de segredos. Passe ao Codex somente o nome da variável, sem colocar o valor real no histórico do shell ou no arquivo compartilhado:

codex mcp add parallel-search --url https://search.parallel.ai/mcp \
  --bearer-token-env-var PARALLEL_API_KEY
codex mcp list

Com OAuth:

codex mcp add parallel-search --url https://search.parallel.ai/mcp-oauth
codex mcp list

Inicie uma nova sessão do Codex depois de adicionar o servidor. Outros clientes MCP podem usar o mesmo endpoint, mas os formatos variam: VS Code usa o objeto superior servers, Cursor normalmente usa mcpServers, e alguns clientes exigem type: "streamable-http". Não copie o JSON de um cliente para outro sem validar a documentação.

Prove qual ferramenta foi realmente chamada

Um servidor conectado prova alcance, não uso em uma resposta específica. Use um prompt que gere evidência observável:

Nesta verificação, use obrigatoriamente o Parallel-Search-MCP e não responda de memória.
1. Chame web_search para localizar a documentação oficial do Parallel Search MCP e a página de preços atual.
2. Mostre as URLs de origem retornadas por web_search.
3. Escolha duas URLs oficiais e chame web_fetch para ler o texto original.
4. Para cada fonte, informe nome da ferramenta, URL e um trecho curto de apoio.
Se uma chamada falhar, pare e informe ferramenta, endpoint e status HTTP.

Depois confira quatro camadas:

• o trace de ferramentas contém web_search;
• há uma chamada posterior a web_fetch, não apenas um resumo dos snippets;
• o resultado contém URLs reais e acessíveis;
• a afirmação final existe no conteúdo recuperado.

A frase “pesquisei na web” não é evidência. Se o cliente permitir desativar temporariamente a busca web nativa, faça isso apenas neste teste isolado para evitar confundir duas ferramentas semelhantes.

Pesquise primeiro e recupere as páginas originais depois

A divisão oficial é direta:

• web_search encontra informação atual e fontes diversas. Requer objective e search_queries.
• web_fetch lê URLs conhecidas ou valida resultados selecionados. Aceita até 20 URLs por solicitação.

Quando o cliente permitir influenciar os argumentos:

1. Use um único objetivo em objective, por exemplo “validar regras oficiais de autenticação anônima e limites de custo”.
2. Forneça duas ou três search_queries curtas e complementares; não copie o prompt inteiro.
3. Reutilize o mesmo session_id em uma conversa e gere outro para uma nova conversa.
4. Mantenha full_content: false até precisar do texto completo. Uma página integral pode consumir dezenas de milhares de tokens do modelo e exceder o limite do cliente.
5. Priorize documentação, especificações e anúncios originais. Trate posts da comunidade como relatos de usuários, não como comportamento universal.

O ciclo busca → seleção de URL → leitura do original → conferência da citação é mais auditável do que uma instrução genérica para “pesquisar na internet”.

Limites de custo: mantenha pelo menos quatro contas

Os preços abaixo foram conferidos na página oficial da Parallel em 11 de outubro de 2026. Eles explicam limites de cobrança, não afirmam que uma opção seja sempre mais barata.

Camada de custo	Assinatura ou associação	Recarga mínima	Crédito do primeiro mês	Base de uso
Search MCP anônimo	A configuração anônima documentada não exige assinatura da conta	Não exige recarga para começar anonimamente	Não há número fixo de chamadas publicado	Descrito como gratuito para exploração e uso leve, com limites menores
Parallel Search/Extract autenticado	A página pública de preços não informa uma taxa separada de assinatura	Não informado	Não há crédito inicial fixo informado	Preço-base do Search (10 resultados incluídos por solicitação): fast/turbo US$1 por 1.000 solicitações; basic/advanced US$5; resultados de página e trechos adicionais: US$1 por 1.000 resultados; Extract: US$1 por 1.000 URLs
Cliente do agente	Depende de Claude Code, Codex ou outro cliente	Específico do cliente	Específico do cliente	Benefícios do plano do cliente não são créditos da Parallel
API do modelo	Específico do provedor	Específico do provedor	Específico do provedor	Entrada, saída, cache e contexto dos resultados são cobrados separadamente do Search MCP

A página do Search MCP não publica uma cota anônima numérica fixa. Não transforme “lower rate limits” em uma promessa inventada de N buscas gratuitas. A tabela geral de rate limits da API também não é garantia do MCP anônimo.

Se uma conexão autenticada retornar 402, a documentação da Parallel associa o erro a créditos insuficientes. Verifique saldo e modo ativo antes de repetir a solicitação.

Se BetterToken fornecer o modelo, mantenha as configurações independentes

Você pode continuar usando Claude Code ou Codex como cliente e adicionar a Parallel somente como camada de ferramentas web:

• Para chamadas do Claude Code via BetterToken, o Base URL é https://bettertoken.ai; o cliente acrescenta /v1/messages, então não adicione /v1 manualmente.
• Para chamadas do Codex via BetterToken, o Base URL é https://www.bettertoken.ai/v1 com wire_api = "responses".
• O endpoint da Parallel continua sendo https://search.parallel.ai/mcp ou https://search.parallel.ai/mcp-oauth.

Essas URLs não são intercambiáveis. BetterToken cuida das chamadas de modelo e do consumo de tokens; Parallel cuida das ferramentas web. Disponibilidade anônima, créditos, privacidade e limites continuam sob as regras do serviço externo. Consulte separadamente o guia do Claude Code, o guia do Codex e a documentação do Parallel Search MCP.

Falhas comuns e o menor reteste útil

Sintoma	Verifique primeiro	Como testar de novo
Servidor adicionado, mas ferramentas ausentes	Reinicie completamente; valide a sintaxe e a URL exata; abra os logs MCP	Confirme web_search e web_fetch
401	Uso de /mcp-oauth, conclusão do OAuth e validade do bearer	Reconecte e confirme que a autenticação deixou de ser solicitada
402	Créditos da conta autenticada	Adicione saldo ou volte ao /mcp anônimo e faça uma busca focada
Conectado, mas sem tool call	O agente pode usar a busca nativa ou responder de memória	Rode o prompt forçado e inspecione o trace
Resultado enorme ou truncado	full_content, URLs demais ou objetivo amplo	Desative conteúdo completo e recupere só páginas relevantes
Comportamento diferente entre projetos	Scope do Claude Code, aprovação do projeto ou sessão antiga do Codex	Liste servidores no projeto e repita a chamada

Quando vale manter a integração

Ela é adequada quando você quer busca hospedada e leitura de páginas sem manter SearXNG, o cliente mostra chamadas e fontes, e o modo anônimo atende tarefas leves ou há orçamento para uso autenticado.

Não leve direto para produção quando precisa de um número gratuito fixo e publicamente garantido, atribuição organizacional ou Zero Data Retention permanecendo anônimo, não consegue inspecionar as chamadas reais ou exige controle total sobre índice, crawler e residência de dados.

A sequência mais segura é executar tarefas representativas no /mcp anônimo, salvar traces e URLs, medir limites e crescimento de tokens do modelo e só migrar para Bearer ou /mcp-oauth quando o modo anônimo virar o gargalo. Assim conexão, qualidade de busca, custo externo e custo do modelo continuam separados e verificáveis.