> ## 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.
# SELECT
> Query the web with SQL — a separate MCP server whose main tool is one read-only SELECT
This server answers a question with **one SQL query over live web search results** — and you do not write that query. You ask your agent a question in plain language; the agent composes a read-only `SELECT` (DuckDB dialect) following the guide the tool ships with itself, and the server runs the searches, fetches the pages, extracts the fields the query asks for with an LLM, deduplicates, and returns a table.
The point is the shape of the answer. One tool call covers many pages at once and comes back as structured rows, instead of the agent reading results one at a time and assembling them by hand.
It is a **separate MCP server** from the [Keenable MCP server](/mcp-server), at its own URL. Adding it does not change the `search_web_pages` / `fetch_page_content` server — you can run both side by side.
```
https://select.keenable.ai/mcp
```
The server also answers on `https://webql.keenable.ai/mcp`, the address it had first.
Neither address redirects to the other, because a redirect ends an MCP session — a client
set up on the old one keeps working, and a new one should use `select.keenable.ai`.
Any Keenable account can connect. Sign up at [app.keenable.ai/signup](https://app.keenable.ai/signup) if you do not have one — the same account you use for the console and API keys. The `/select` playground in the console is still invitation-only; the MCP server is not.
## Connect
Two credentials work: a browser sign-in, or an API key in a header. Which of them you can
use depends on the client, so go to the one you use.
Browser sign-in, or your own key in a header
Desktop, claude.ai and mobile, as a custom connector
Developer mode, added by URL
Any client that takes a URL and a header
### One click
Cursor and VS Code take the server from a link. They add it without a key, so it signs you
in on first use.
### Claude Code
Sign in through the browser, with no key to paste:
```bash theme={"system"}
claude mcp add keenable-select \
--transport http https://select.keenable.ai/mcp \
--scope user
```
Then run `/mcp` in a session, pick **keenable-select**, and choose **Authenticate**. Your browser opens a Keenable sign-in; approve it and the tools appear.
To use an API key instead — created in the [console](https://app.keenable.ai/console) — add the header and skip the sign-in:
```bash theme={"system"}
claude mcp add keenable-select \
--transport http https://select.keenable.ai/mcp \
--scope user \
--header "X-API-Key: keen_"
```
`--scope user` makes the server available in every project. Without it the entry is written for the current directory only.
### Claude Desktop, claude.ai and mobile
These connect through the **custom connector** UI, and sign you in instead of taking a key.
The UI has no field for a request header, so use Claude Code or another client that sends
headers if you need a specific API key applied.
**Settings → Connectors → Add custom connector** (or **+** in the composer → **Connectors**). Paste the URL and leave OAuth Client ID / Secret **empty** — the server advertises its own authorization server and Claude registers itself:
```
https://select.keenable.ai/mcp
```
A newly added connector is not active until you connect it. Open **Manage connectors**, find it, and click **Connect**. Your browser opens a Keenable sign-in; approve it and the tools appear.
In the composer, click **+ → Connectors** and toggle it on for the conversation.
Give it a name that distinguishes it from the standard Keenable connector — e.g. **Keenable SELECT** — since they are separate servers with different tools.
### ChatGPT
ChatGPT reaches a custom MCP server through **developer mode**, not through the plugin directory — the directory listing is the [Keenable search plugin](/integrations/chatgpt), a different server.
**Settings → Connectors → Advanced settings → Developer mode**. Without it, ChatGPT offers no way to add a server by URL.
**Settings → Connectors → Create**, paste the URL, and choose **OAuth** as the authentication:
```
https://select.keenable.ai/mcp
```
Sign in when the browser opens. There is no client ID or secret to fill in.
Pick the connector from the composer's tools menu before asking. A query runs for as long as it needs; see [What to expect](#what-to-expect).
Deep research in ChatGPT accepts only connectors that expose `search` and `fetch` tools. This server exposes `select` instead, so use it as an ordinary developer-mode connector, and the [Keenable plugin](/integrations/chatgpt) for deep research.
### Codex, Cursor and other clients
Any client that takes a remote MCP URL and a header works. Create a key in the [console](https://app.keenable.ai/console) first.
Codex — add to `~/.codex/config.toml`:
```bash theme={"system"}
[mcp_servers.keenable-select]
url = "https://select.keenable.ai/mcp"
http_headers = { "X-API-Key" = "keen_" }
```
Cursor, Windsurf, and similar:
```json theme={"system"}
{
"mcpServers": {
"keenable-select": {
"url": "https://select.keenable.ai/mcp",
"headers": {
"X-API-Key": "keen_"
}
}
}
}
```
An `Authorization: Bearer keen_` header works too, if your client only offers that field.
## The tools
The main tool is `select`. Its parameters are filled in by the agent, not by you; they are listed here so you can read a transcript and see what was actually run.
A single read-only `SELECT` in DuckDB dialect. Web pages enter the query through the `WEB_SEARCH(...)` and `WEB_FETCH(...)` table functions; the `SEM_*` functions extract, filter, rank and normalise values with an LLM.
Return a small sample of rows instead of the full table. Defaults to `false`.
Nobody has to teach the agent this dialect, and you do not have to learn it yourself. The `select` tool carries its own full usage guide as its description — syntax, semantic functions and worked examples — so the model has everything it needs the moment the connector is enabled.
Two more tools publish what a query found as a web page: `generate_html_report` builds a document from a brief plus the result sets you name and returns its link, and `revoke_html_report` takes that link back down.
So a session reads like an ordinary conversation. You ask *"which electric cars sold in Europe come up most often, and what are their range and starting price?"*; the agent turns that into a query like this:
```sql theme={"system"}
SELECT SEM_NORM(model, 'merge trim levels and battery variants into one model') AS model,
COUNT(DISTINCT url) AS sources,
MODE(range_km) AS range_km,
MODE(price_eur) AS price_eur
FROM (
SELECT url, UNNEST(
SEM_EXTRACT_ALL(
content,
'an electric car model sold in Europe',
model := 'brand and model name, e.g. "Renault 5 E-Tech"',
range_km := 'WLTP range in km, number only',
price_eur := 'starting price in EUR, number only'
),
recursive := true
)
FROM WEB_SEARCH(
'best electric cars Europe 2026 WLTP range price',
'affordable EV Europe comparison starting price',
'new electric car launches Europe 2026',
'EV buyers guide range price Germany',
'site:reddit.com which EV should I buy Europe',
'electric car WLTP range comparison table',
'cheapest electric cars Europe list'
)
)
GROUP BY SEM_NORM(model, 'merge trim levels and battery variants into one model')
ORDER BY sources DESC
LIMIT 15
```
That is one tool call. It ran seven searches, merged 1,400 results into 1,125 unique pages, extracted three fields from each and grouped them, and came back with this (first 8 of 15 rows):
| model | sources | range\_km | price\_eur |
| ---------------- | ------- | --------- | ---------- |
| Tesla Model Y | 119 | 455 | 39990 |
| Tesla Model 3 | 118 | 580 | 44990 |
| Renault 5 E-Tech | 113 | 400 | 25000 |
| Dacia Spring | 91 | 225 | 16900 |
| Citroen e-C3 | 81 | 320 | 23300 |
| BMW iX3 | 78 | 805 | 70900 |
| Leapmotor T03 | 77 | 265 | 18900 |
| Volkswagen ID.3 | 65 | 420 | 35000 |
That is a real run, and the figures are whatever the pages said — the server reports its sources, it does not audit them. See [What to expect](#what-to-expect).
The seven searches are the point of the shape: the guide tells the agent to cast wide with genuinely different phrasings rather than variations of one, and the pages they return are merged and deduplicated by URL before the rest of the query runs. On the wire the rows arrive in a compact tabular encoding rather than JSON, which is why a table this size costs so little context.
## Result sets
Every call stores its output and returns a **result set id** — `ra84968f0532` for the query above. A later query reads it by putting that id in `FROM`, so a follow-up costs no new searching.
That is what makes the second question cheap. Ask *"now just the ones under €30,000, longest range first"* and the agent queries the stored table instead of going back to the web:
```sql theme={"system"}
SELECT model, range_km, price_eur
FROM ra84968f0532
WHERE TRY_CAST(price_eur AS INTEGER) < 30000
ORDER BY TRY_CAST(range_km AS INTEGER) DESC
```
| model | range\_km | price\_eur |
| ---------------- | --------- | ---------- |
| Renault 5 E-Tech | 400 | 25000 |
| Citroen e-C3 | 320 | 23300 |
| Leapmotor T03 | 265 | 18900 |
| Dacia Spring | 225 | 16900 |
| BYD Dolphin Surf | 220 | 18990 |
That one returned in seconds, because no page was searched or fetched. The searched pages are also kept as their own result set, so a different question can be asked of the same 1,125 pages without paying for the crawl twice.
Result sets are kept for **30 days**.
## What to expect
* **Queries are slow by ordinary tool standards** — seconds to minutes, because each one runs real searches, fetches pages and calls an LLM per row. That is normal, not a hang.
* **Large tables come back as a preview.** Above roughly 50,000 characters the response degrades to a few sample rows with long strings clipped; the full table stays available through the result set id.
* **A report takes minutes to build**, and a client that gives up on a slow tool call cancels it. Ask for a report from aggregated result sets rather than a raw table of hundreds of rows, so it finishes before the client stops waiting.
* **Extraction does not fact-check its sources.** A single page can be outdated or the wrong edition, so cross-check precise numbers across independent pages.
## When something is refused
* **401** — no credential reached the server, or it is invalid. Check the header name and the key.
* **429** — too many queries at once, cluster-wide. Retry shortly.
* **403** — this deployment runs an allowlist and the account is not on it. Production does not, so you should not see this; if you do, email [support@keenable.ai](mailto:support@keenable.ai) with the address you signed in with. Signing in again will not clear it.