> ## Documentation Index > Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP > Connect Keenable APIs as tools to clients that support MCP The Keenable tools are also available as a Model Context Protocol server, so agents like Claude Code, Claude Desktop, Cursor, and Windsurf can call them directly. Pass your API key in the `X-API-Key` header to remove the hourly request limit and raise rate limits — see [Authentication](/authentication) and [Rate limits](/rate-limits). Drop the header and the server still answers, on the shared public tier. ## Installation ### One-click install Add Keenable to Cursor, VS Code or Replit with a single click: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=keenable\&config=eyJ1cmwiOiJodHRwczovL2FwaS5rZWVuYWJsZS5haS9tY3AifQ==) [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22keenable%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.keenable.ai%2Fmcp%22%7D) [Add to VS Code Insiders](vscode-insiders:mcp/install?%7B%22name%22%3A%22keenable%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.keenable.ai%2Fmcp%22%7D) [Add to Replit](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IktlZW5hYmxlIiwiYmFzZVVybCI6Imh0dHBzOi8vYXBpLmtlZW5hYmxlLmFpL21jcC1vYXV0aCJ9) ### Install via CLI The easiest way to set up the Keenable MCP server for local coding agents is via the [Keenable CLI](/cli). Once you've installed the CLI, run the following to be guided through the MCP server setup. ```shellscript theme={"system"} keenable configure-mcp ``` ### Claude Code Add the Keenable MCP server with the Claude Code CLI: ```bash theme={"system"} claude mcp add keenable \ --transport http https://api.keenable.ai/mcp \ --scope user \ --header "X-API-Key: keen_" ``` Omit the `--header` flag to run on the public tier instead. > [!NOTE] > > Claude Code ships its own `WebSearch` and `WebFetch` tools and picks between them and Keenable from one lookup to the next. Add `"permissions": { "deny": ["WebSearch", "WebFetch"] }` to `~/.claude/settings.json` to leave Keenable as the only search; see [Claude](/integrations/claude#turn-off-the-built-in-search) for the details and how to undo it. ### Codex Add the following to `~/.codex/config.toml` ```toml theme={"system"} [mcp_servers.keenable] url = "https://api.keenable.ai/mcp" http_headers = { "X-API-Key" = "keen_" } ``` Omit the `http_headers` line to run on the public tier instead. > [!NOTE] > > **Codex needs one more line.** It ships its own web search, enabled by default, and keeps reaching for that instead — so the tools show up in `/mcp` but never get called unless you ask for them by name. Add `web_search = "disabled"` to the same file, **above** the `[mcp_servers.keenable]` line — it's a top-level key, and a bare key written under a table header belongs to that table instead, where Codex never reads it. See [Codex](/integrations/codex) for the finished file, the other modes, and an `AGENTS.md` snippet. ### Other MCP clients For Cursor and other clients that accept a remote MCP URL in their config file: ```json theme={"system"} { "mcpServers": { "keenable": { "url": "https://api.keenable.ai/mcp", "headers": { "X-API-Key": "keen_" } } } } ``` Omit the `headers` block to run on the public tier instead. > [!WARNING] > > **Claude Desktop is not one of these clients.** Its config file accepts only local `command` servers, so a `"url"` entry is ignored without an error and the tools never appear. Use a [connector](#claude-remote-connector) instead, or the [local bridge](#local-bridge-with-an-api-key) if you want your key applied. ### OpenAI API (Responses API) This is for calling the MCP server from your own code against OpenAI's API — different from adding Keenable inside the ChatGPT app itself, which is the [Plugins Directory listing](/integrations/chatgpt). Pass it as a remote `mcp` tool: ```python theme={"system"} 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_"}, "require_approval": "never", } ], ) print(response.output_text) ``` Omit the `headers` entry to run on the public tier instead. > [!NOTE] > > Keenable's search and fetch cover the same ground as a client's own built-in tools > (`WebSearch`, `WebFetch`, `brave_search`, `tavily_search`). With both sets active an agent > picks between them inconsistently from one call to the next, so most people turn the > built-in ones off in client settings once Keenable is in place. ### Claude (remote connector) Claude (Desktop, claude.ai, mobile) connects to the remote MCP server as a **connector**, with no config file. The connection is made from Anthropic's cloud, so your server just needs to be reachable at its public URL. > [!NOTE] > > **[ChatGPT](/integrations/chatgpt) installs from the Plugins Directory** — Keenable is published there, so it comes from the catalog and signs you in to your Keenable account. [Codex](/integrations/codex) can install from the same listing, but has a `config.toml` route of its own. **1. Add the connector** Keenable is listed in Claude's Connectors Directory as **Keenable Web Search**: open **Customize → Connectors**, click **+**, search for it, and click **Connect**. There is nothing to paste. To run on your own Keenable account, add it by URL instead: **Customize → Connectors → + Add → Add custom connector** with the URL below, then click **Connect** and sign in to Keenable. An API key in a request header works too; see [Claude](/integrations/claude#use-your-own-account). ``` https://api.keenable.ai/mcp-oauth ``` **2. Enable it in a chat** Click **+** in the lower left of the message box, hover **Connectors**, and toggle Keenable on for the conversation. To stop Claude's own web search from competing with Keenable, see [Claude](/integrations/claude#turn-off-web-search). ### Local bridge (with an API key) Any client that only speaks local stdio needs a bridge to apply your own key. Claude Desktop's config file is the common case. `@keenable/mcp-server` runs as a subprocess and forwards to the same endpoint: ```json theme={"system"} { "mcpServers": { "keenable": { "command": "npx", "args": ["-y", "@keenable/mcp-server"], "env": { "KEENABLE_API_KEY": "keen_" } } } } ``` Needs Node.js on the machine, and the client has to be restarted after editing its config file (for Claude Desktop, `claude_desktop_config.json`). Drop the `env` block to run it without a key. The same block works verbatim in any other stdio-only client's config, not just Claude Desktop's. ## Available tools Two tools are exposed by the MCP server. ### `search_web_pages` Search the web and return ranked results with URLs, titles, and descriptions. **query** `string` *required* The search query. **site** `string` Restrict results to a specific site (e.g. `"techcrunch.com"`). **acquired\_after** `string` Filter to pages acquired/indexed at or after this point in time. **acquired\_before** `string` Filter to pages acquired/indexed at or before this point in time. **published\_after** `string` Filter to pages published at or after this point in time. **published\_before** `string` Filter to pages published at or before this point in time. **query\_time** `string` Search the index as it stood at this point in time: pages acquired after it are excluded. Accepts a timestamp or a date (a date resolves to `00:00:00` UTC, not to the end of the day). See [Point-in-time search](#point-in-time-search). **snippet\_max\_length** `integer` Maximum length, in characters, of the snippet returned per result. Must be between 180 and 10000. When omitted, a default snippet length is used. **max\_results** `integer` Maximum number of results to return. Must be between 1 and 50. When omitted, up to 10 results are returned. #### Date and time filters `acquired_after`, `acquired_before`, `published_after`, and `published_before` each accept **one** of the following formats: * **Date** in RFC 3339 `full-date` form (`YYYY-MM-DD`) — covers that whole day in UTC. On an `_after` bound it resolves to `00:00:00` on that date; on a `_before` bound it resolves to `23:59:59.999` on that date, so pages from the named day are kept at either end. Pass a timestamp instead to cut at an exact instant. * **Timestamp** in ISO 8601 form (`YYYY-MM-DDTHH:MM:SS[.sss][±HH:MM]`). When a timezone offset is not provided, the timezone is interpreted as UTC. * **Relative delta** (``, e.g. `7d`, `30min`) — resolves to the request time minus the delta, truncated to minute precision, or to [`query_time`](#point-in-time-search) minus the delta when that is set. Supported units: `min` (minutes), `h` (hours), `d` (days), `mo` (months), `y` (years). Example values: | Value | Resolves to | | - | - | | `2026-01-15` on `acquired_after` / `published_after` | `2026-01-15T00:00:00Z` | | `2026-01-15` on `acquired_before` / `published_before` | `2026-01-15T23:59:59.999Z` | | `2026-01-15T10:30:00` | `2026-01-15T10:30:00Z` (no offset → UTC) | | `2026-01-15T10:30:00Z` | `2026-01-15T10:30:00Z` | | `2026-01-15T10:30:00.500-05:00` | `2026-01-15T15:30:00.500Z` | | `7d` | 7 days before request time, truncated to the minute | | `30min` | 30 minutes before request time, truncated to the minute | Relative deltas may be combined with absolute values across the two bounds of a window: ```json theme={"system"} { "query": "...", "published_after": "1y", "published_before": "6mo" } ``` ```json theme={"system"} { "query": "...", "acquired_after": "2024-01-01", "acquired_before": "30d" } ``` For example, at request time `2026-05-18T14:23:45Z`, `acquired_after: "2h"` resolves to `2026-05-18T12:23:00Z` — a document acquired at `12:22:59Z` is dropped, one acquired at `12:23:00Z` is kept. Mind the difference between a date and a timestamp on a `_before` bound: `acquired_before: "2026-05-01"` keeps a page acquired at `2026-05-01T14:31:13Z`, while `acquired_before: "2026-05-01T00:00:00Z"` drops it. Use the date form to mean "up to and including that day", and the timestamp form to cut at midnight. #### Point-in-time search `query_time` moves the whole search back to an instant: a page acquired after it is not a candidate at all, so the answer is the one the index would have given then rather than today's answer filtered down. Reach for it to reproduce an agent run, to build an evaluation set that does not drift as the index grows, or to ask what was knowable before an event. It also **re-bases every relative delta on this request**. A delta resolves against the request time only when `query_time` is absent; with it, `published_after: "30d"` means thirty days before `query_time`: ```json theme={"system"} { "query": "...", "query_time": "2026-06-13T00:00:00Z", "published_after": "30d" } ``` resolves to pages published between `2026-05-14` and `2026-06-13` — not to the last thirty days. Absolute bounds are unaffected. A date-only `query_time` resolves to `00:00:00` UTC, which is the opposite end of the day from a date-only `_before` bound: `query_time: "2026-06-13"` cuts at the start of 13 June, while `acquired_before: "2026-06-13"` keeps all of it. ### `fetch_page_content` Fetch a URL and extract content as clean markdown. By default only URLs from the index are supported; this is not a general web scraper. Pass `live=true` to fetch directly from the source, including URLs that are not indexed. **url** `string` *required* The URL to fetch. **max\_chars** `integer` (default: 50000) Maximum number of characters of content to return. Longer content is truncated. **live** `boolean` (default: false) Fetch the page live from the source instead of returning Keenable's indexed copy. Enables fetching URLs that are not indexed. **prompt** `string` Optional extraction instruction, at most 2000 characters. When set, an LLM reads the fetched page and the returned content is only the output for this instruction instead of the full page. Example: `List all pricing tiers with their monthly prices`. Returns `url`, `title`, and `content` (markdown). See the [Fetch reference](/api-reference/fetch) for the response shape. ## Metadata for integrators Platforms embedding Keenable's MCP tools can read billing usage and control tool behaviour through the MCP `_meta` side channel. `_meta` travels alongside the tool result or request and is **not** part of the model-visible tool `content`, so none of it enters the agent's context. [Baseten](/integrations/baseten) uses both channels to run the tools as hosted tools on its Model APIs. ### Usage metadata (response `_meta`) Every billed (authenticated) tool call returns usage under `_meta["keenable/usage"]`, so you can attribute cost per call without parsing the tool's text output. Unauthenticated calls are unbilled and omit it. **sku** `string` Billing SKU for the operation: `search.realtime`, `search.pro`, `fetch`, or `fetch.live`. **amount** `integer` Number of billed operations — always `1` for a single tool call. **credits** `number` Credits metered for this call (the org-specific price for the operation). **paid** `boolean` `true` when drawn from purchased credits; `false` while still on the free monthly allowance. See [credits](/credits). Example tool result: ```json theme={"system"} { "content": [{ "type": "text", "text": "..." }], "_meta": { "keenable/usage": { "sku": "search.realtime", "amount": 1, "credits": 1, "paid": true } } } ``` ### Operator overrides (request `_meta`) To control tool behaviour yourself instead of letting the model decide, send overrides under `_meta["keenable/overrides"]` on a `tools/call` request. They take precedence over the arguments the model generated. **mode** `string` Force the search mode: `realtime` or `pro`. Overrides any `mode` the model chose. **skip\_cache** `boolean` Bypass cached results for this call. Example request: ```json theme={"system"} { "method": "tools/call", "params": { "name": "search_web_pages", "arguments": { "query": "..." }, "_meta": { "keenable/overrides": { "mode": "realtime", "skip_cache": true } } } } ``` Invalid or unknown override values are ignored rather than erroring the call. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.