Keenable Web Search

MCP

Conecte as APIs da Keenable como ferramentas a clientes que suportam MCP

As ferramentas da Keenable também estão disponíveis como um servidor Model Context Protocol, para que agentes como Claude Code, Claude Desktop, Cursor e Windsurf possam chamá-las diretamente. Envie sua chave de API no cabeçalho X-API-Key para remover o limite de solicitações por hora e aumentar os limites de taxa — consulte Autenticação e Limites de taxa. Remova o cabeçalho e o servidor ainda responde, no nível público compartilhado.

Instalação

Instalação com um clique

Adicione a Keenable ao Cursor ou VS Code com um único clique:

Adicionar ao Cursor

Adicionar ao VS Code

Adicionar ao VS Code Insiders

Instalação via CLI

A maneira mais fácil de configurar o servidor MCP da Keenable para agentes de codificação locais é através da CLI da Keenable. Depois de instalar a CLI, execute o seguinte para ser guiado pela configuração do servidor MCP.

keenable configure-mcp

Claude Code

Adicione o servidor MCP da Keenable com a CLI do Claude Code:

claude mcp add keenable \
  --transport http https://api.keenable.ai/mcp \
  --scope user \
  --header "X-API-Key: keen_<your_key>"

Omita a flag --header para executar no nível público.

Codex

Adicione o seguinte ao ~/.codex/config.toml

[mcp_servers.keenable]
url = "https://api.keenable.ai/mcp"
http_headers = { "X-API-Key" = "keen_<your_key>" }

Omita a linha http_headers para executar no nível público.

Nota

O Codex precisa de mais uma linha. Ele vem com sua própria busca na web, habilitada por padrão, e continua usando essa em vez da sua — então as ferramentas aparecem em /mcp mas nunca são chamadas, a menos que você as peça pelo nome. Adicione web_search = "disabled" ao mesmo arquivo, acima da linha [mcp_servers.keenable] — é uma chave de nível superior, e uma chave simples escrita sob um cabeçalho de tabela pertence àquela tabela, onde o Codex nunca a lê. Consulte Codex para ver o arquivo finalizado, os outros modos e um trecho de AGENTS.md.

Outros clientes MCP

Para Cursor e outros clientes que aceitam uma URL MCP remota em seu arquivo de configuração:

{
  "mcpServers": {
    "keenable": {
      "url": "https://api.keenable.ai/mcp",
      "headers": {
        "X-API-Key": "keen_<your_key>"
      }
    }
  }
}

Omita o bloco headers para executar no nível público.

Aviso

O Claude Desktop não é um desses clientes. Seu arquivo de configuração aceita apenas servidores command locais, então uma entrada "url" é ignorada sem erro e as ferramentas nunca aparecem. Use um conector ou a ponte local se quiser aplicar sua chave.

API OpenAI (API Responses)

Isso é para chamar o servidor MCP a partir do seu próprio código contra a API da OpenAI — diferente de adicionar a Keenable dentro do aplicativo ChatGPT, que é a listagem no diretório de plugins. Passe como uma ferramenta mcp remota:

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5",
    input="What's new in retrieval-augmented generation this week?",
    tools=[
        {
            "type": "mcp",
            "server_label": "keenable",
            "server_url": "https://api.keenable.ai/mcp",
            "headers": {"X-API-Key": "keen_<your_key>"},
            "require_approval": "never",
        }
    ],
)
print(response.output_text)

Omita a entrada headers para executar no nível público.

Nota

A busca e a extração da Keenable cobrem o mesmo terreno que as ferramentas integradas de um cliente (WebSearch, WebFetch, brave_search, tavily_search). Com ambos os conjuntos ativos, um agente escolhe entre eles de forma inconsistente de uma chamada para outra, então a maioria das pessoas desativa os integrados nas configurações do cliente assim que a Keenable está instalada.

Claude (conector remoto)

O Claude (Desktop, claude.ai, mobile) conecta-se ao servidor MCP remoto através da interface de conector personalizado — sem necessidade de arquivo de configuração. A conexão é feita a partir da nuvem da Anthropic, então seu servidor só precisa estar acessível em sua URL pública.

Nota

ChatGPT instala a partir do diretório de plugins — a Keenable está publicada lá, então vem do catálogo e faz login na sua conta Keenable. O Codex pode instalar a partir da mesma listagem, mas tem uma rota config.toml própria.

Caso contrário, adicione por URL — **Configurações → Conectores → Adicionar conector personalizado** — deixando OAuth Client ID / Secret vazio:

```
https://api.keenable.ai/mcp
```

Ponte local (com chave de API)

Qualquer cliente que só fale stdio local — o arquivo de configuração do Claude Desktop é o caso comum, já que sua interface de conector não tem campo para cabeçalho — precisa de uma ponte para aplicar sua própria chave. @keenable/mcp-server roda como um subprocesso e encaminha para o mesmo endpoint:

{
  "mcpServers": {
    "keenable": {
      "command": "npx",
      "args": ["-y", "@keenable/mcp-server"],
      "env": {
        "KEENABLE_API_KEY": "keen_<your_key>"
      }
    }
  }
}

Requer Node.js na máquina, e o cliente precisa ser reiniciado após editar seu arquivo de configuração (para Claude Desktop, claude_desktop_config.json). Remova o bloco env para executar sem chave. O mesmo bloco funciona igual em qualquer outro cliente somente stdio, não apenas no Claude Desktop.

Ferramentas disponíveis

Duas ferramentas são expostas pelo servidor MCP.

search_web_pages

Busque na web e retorne resultados classificados com URLs, títulos e descrições.

Filtros de data e hora

acquired_after, acquired_before, published_after e published_before aceitam cada um um dos seguintes formatos:

• Data no formato RFC 3339 full-date (YYYY-MM-DD) — cobre o dia inteiro em UTC. Em um limite _after, resolve para 00:00:00 nessa data; em um limite _before, resolve para 23:59:59.999 nessa data, então páginas do dia nomeado são mantidas em qualquer extremidade. Passe um timestamp para cortar em um instante exato.
• Timestamp no formato ISO 8601 (YYYY-MM-DDTHH:MM:SS[.sss][±HH:MM]). Quando um offset de fuso horário não é fornecido, o fuso é interpretado como UTC.
• Delta relativo (<number><unit>, ex.: 7d, 30min) — resolve para o tempo da solicitação menos o delta, truncado para precisão de minuto, ou para query_time menos o delta quando isso está definido. Unidades suportadas: min (minutos), h (horas), d (dias), mo (meses), y (anos).

Exemplos de valores:

Deltas relativos podem ser combinados com valores absolutos nos dois limites de uma janela:

{
  "query": "...",
  "published_after": "1y",
  "published_before": "6mo"
}

{
  "query": "...",
  "acquired_after": "2024-01-01",
  "acquired_before": "30d"
}

Por exemplo, no tempo de solicitação 2026-05-18T14:23:45Z, acquired_after: "2h" resolve para 2026-05-18T12:23:00Z — um documento adquirido em 12:22:59Z é descartado, um adquirido em 12:23:00Z é mantido.

Preste atenção à diferença entre data e timestamp em um limite _before: acquired_before: "2026-05-01" mantém uma página adquirida em 2026-05-01T14:31:13Z, enquanto acquired_before: "2026-05-01T00:00:00Z" a descarta. Use a forma de data para significar "até e incluindo aquele dia", e a forma de timestamp para cortar à meia-noite.

Busca em ponto no tempo

query_time move toda a busca de volta para um instante: uma página adquirida depois não é candidata de forma alguma, então a resposta é a que o índice teria dado naquele momento, em vez da resposta de hoje filtrada. Use para reproduzir uma execução de agente, para construir um conjunto de avaliação que não se desvie conforme o índice cresce, ou para perguntar o que era conhecível antes de um evento.

Também rebaseia cada delta relativo nesta solicitação. Um delta resolve contra o tempo da solicitação apenas quando query_time está ausente; com ele, published_after: "30d" significa trinta dias antes de query_time:

{
  "query": "...",
  "query_time": "2026-06-13T00:00:00Z",
  "published_after": "30d"
}

resolve para páginas publicadas entre 2026-05-14 e 2026-06-13 — não para os últimos trinta dias. Limites absolutos não são afetados.

Um query_time somente data resolve para 00:00:00 UTC, que é a extremidade oposta do dia em relação a um limite _before somente data: query_time: "2026-06-13" corta no início de 13 de junho, enquanto acquired_before: "2026-06-13" mantém o dia inteiro.

fetch_page_content

Busque uma URL e extraia o conteúdo como markdown limpo. Por padrão, apenas URLs do índice são suportadas; isso não é um raspador web geral. Passe live=true para buscar diretamente da fonte, incluindo URLs que não estão indexadas.

Retorna url, title e content (markdown). Consulte a referência de Fetch para a forma da resposta.

Metadados para integradores

Plataformas que incorporam as ferramentas MCP da Keenable podem ler o uso de cobrança e controlar o comportamento das ferramentas através do canal lateral _meta do MCP. _meta viaja junto com o resultado ou solicitação da ferramenta e não faz parte do content da ferramenta visível ao modelo, então nada disso entra no contexto do agente.

Metadados de uso (_meta de resposta)

Toda chamada de ferramenta cobrada (autenticada) retorna uso sob _meta["keenable/usage"], para que você possa atribuir custo por chamada sem analisar a saída de texto da ferramenta. Chamadas não autenticadas não são cobradas e o omitem. SKU de cobrança para a operação: search.realtime, search.pro, fetch ou fetch.live.

Exemplo de resultado da ferramenta:

{
  "content": [{ "type": "text", "text": "..." }],
  "_meta": {
    "keenable/usage": { "sku": "search.realtime", "amount": 1, "credits": 1, "paid": true }
  }
}

Substituições do operador (solicitação _meta)

Para controlar o comportamento da ferramenta por conta própria, em vez de deixar o modelo decidir, envie substituições sob _meta["keenable/overrides"] em uma solicitação tools/call. Elas têm precedência sobre os argumentos gerados pelo modelo.

Exemplo de solicitação:

{
  "method": "tools/call",
  "params": {
    "name": "search_web_pages",
    "arguments": { "query": "..." },
    "_meta": { "keenable/overrides": { "mode": "realtime", "skip_cache": true } }
  }
}

Valores de substituição inválidos ou desconhecidos são ignorados em vez de gerar erro na chamada.