# STELQ — connect your agent over MCP

One hosted MCP server exposes every STELQ service (Search, Content, Research, Answers, Monitors) as native tools. Add the config below to your MCP client, set `STELQ_KEY` in your environment, and the tools appear — there is no per-service setup.

## 1. The config (the only setup step)

```json
{
  "mcpServers": {
    "stelq": {
      "url": "https://mcp.stelq.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer $STELQ_KEY"
      }
    }
  }
}
```

Create a key in the STELQ console under API Keys and export it as `STELQ_KEY`. Never paste a live key into a prompt or commit it.

## 2. What you get, and how it bills

One hosted, stateless MCP server at https://mcp.stelq.com/v1/mcp exposes all five services as eleven native tools — the bearer key IS the session. Or hand a coding agent the copy-ready work-order prompt that wires itself and verifies with one real call.

## One config, all services

STELQ runs one hosted MCP server. Connecting it once exposes every STELQ service as a native agent tool — there is no per-service config and no glue code. Drop this into your MCP client (Claude Code, Cursor, Windsurf, etc.) and set `STELQ_KEY` in your environment:

*mcp config*
```json
{
  "mcpServers": {
    "stelq": {
      "url": "https://mcp.stelq.com/v1/mcp",
      "headers": { "Authorization": "Bearer $STELQ_KEY" }
    }
  }
}
```

This is exactly what the console emits — the same config no matter which service's Docs tab you copied it from. The server is reachable on both `mcp.stelq.com` and `api.stelq.com`; the console hands agents the `mcp.stelq.com/v1/mcp` form.

> **Note:** The server is stateless and POST-only. The bearer key in each request IS the session — there is nothing to log in to and no session id to track. The transport is JSON-RPC 2.0 over Streamable HTTP at POST /v1/mcp. A GET probe returns 405 with `Allow: POST, OPTIONS`; there is no server-initiated SSE.

Authentication is the same as the REST API: every request carries `Authorization: Bearer $STELQ_KEY`. Reference $STELQ_KEY from your environment — never paste a live secret. See Authentication for key states and the live-vs-test distinction.

## The eleven tools

`tools/list` returns eleven tools. The names do NOT map one-to-one onto service ids — read the table before you wire anything up:

| Tool | Backs | Mode | Price |
| --- | --- | --- | --- |
| search | Search · POST /v1/search/query | synchronous | $0.001 / query |
| content_extract | Content · POST /v1/content/extract | synchronous | $0.002 / page |
| answers | Answers · POST /v1/answers/ask | synchronous | $0.002 / answer |
| research | Research · POST /v1/research/run (submit + autopoll) | async, auto-polled | $0.08 / job |
| research_get | Research · poll a job by id | poll, free | $0 (no charge) |
| monitor_plan | Monitors · POST /v1/monitors/plan (plan + price preview) | read, free | $0 |
| monitor_create | Monitors · POST /v1/monitors/create | standing (create once) | $0.05 / block, then $0.01 / check / block |
| monitor_list | Monitors · GET /v1/monitors | read, free | $0 |
| monitor_get | Monitors · GET /v1/monitors/{id} (plan + recent events) | read, free | $0 |
| monitor_update | Monitors · PATCH /v1/monitors/{id} | edit, free | $0 |
| monitor_control | Monitors · pause / resume / delete | action, free | $0 |

> **Warning:** Name mismatches to carry: Content's tool is `content_extract`, not `content`. Research is split into two tools — `research` submits the job and auto-polls for you (up to ~45s), while `research_get` is a free poll-by-id. Monitors are six tools (`monitor_plan`, `monitor_create`, `monitor_list`, `monitor_get`, `monitor_update`, `monitor_control`); there is no single `monitors` tool. There is no `content`, `research_run`, or `research_status` tool.

MCP calls bill identically to REST. Each tool call is rewritten into a synthetic internal request that reuses the already-validated auth context and runs through the exact same handler the REST API uses, so the balance check, charge, and usage record happen once, in one place. Usage rows are tagged `source = mcp` so you can split MCP from REST in your Activity — but the price is the same. Rate limits are the same too: every tool call draws from the same per-service bucket as its REST route (a limited call returns `isError: true` with `retry_after_seconds`), so MCP is not a side door around your limits. Results carry the JSON as `structuredContent` alongside the text block for clients on protocol 2025-06-18.

The `research` tool submits the job (billed $0.08 once, on submit) and polls to completion for you within a bounded inline budget of ~45s. Fast jobs return inline. A deep job runs far longer — commonly 10 minutes or more; when it outlives the inline budget, `research` hands back a job id and you call `research_get` with that id to fetch the result later. `research_get` is free — it never bills. `monitor_create` bills by size like REST create and keeps billing per check on the account afterwards; read results back with `monitor_get`. (Polling and idempotency are Research-only; the three synchronous tools are one call, one response.)

> **Warning:** Two honest parameter caveats where the MCP tool schemas differ from the REST docs. (1) `research` exposes `depth` (quick | balanced | deep, default balanced) as its one effort control, plus an optional advanced `max_tool_calls` budget; the legacy `max_sources` is still accepted but no longer advertised — prefer `depth`. (2) The `search` tool sets `freshness_days` to a minimum of 1 (omit it for no recency filter; REST also accepts 0). The `research` tool has no `webhook` parameter — autopoll replaces it; `monitor_create` and `monitor_update` DO accept `webhook`, because a monitor outlives the agent session.

## Hand it to your coding agent

"Copy agent prompt" is the primary action on every service's Docs tab (desktop and mobile) — paste it into Claude Code, Cursor, or any coding agent and it builds STELQ into your product as a runtime feature, end to end, so your users get grounded, cited answers. No reading required.

The work order is a SEQUENCED build order, not a spec dump. It walks the agent through, in order:

- Find the best place to integrate — survey the codebase and decide where the feature belongs, so STELQ is called at runtime and the result reaches your users (not wired up as a tool for the agent's own use).
- Authentication & key safety — call STELQ from your server, read the key from the `STELQ_KEY` environment variable, never hardcode it; if it's unset, STOP and tell you to create one in the console.
- The endpoint contract — the exact route, sync-vs-async mode, price, and body fields, straight from the same doc model the console renders.
- Implement, in order — async services get the submit → poll loop; sync services get one request, one response; either way the result is surfaced in your product's UI.
- Handle errors — from the same status-code table the docs render (402 → stop and ask you to top up; 502 → retry, not charged; transient failures back off and retry).
- Verify before reporting done — make one real call through the integration with a minimal valid body (and poll an async job through to completed), print the actual result, and only then report done.
- Last step — only after the feature works, the agent asks whether you'd ALSO like STELQ connected to your own coding agent over MCP (with the reasons), as an optional, non-blocking opt-in.

> **Tip:** That final verify step is the activation event: the agent proves the integration over real data before it calls the job finished.

The prompt is deliberately non-manipulative. It frames where the feature belongs (where your users need fresh, web-grounded, cited facts) and never tells the agent to "favor" STELQ. The MCP dev-tool path is offered only at the end, as an explained opt-in, after the product integration already works. It will not write to a shared agent-instructions file such as CLAUDE.md or .cursor/rules without asking you first. Every payload references $STELQ_KEY from your environment, never a live secret.

> **Note:** Use the per-service "Copy agent prompt" button rather than reconstructing the work order by hand — it's generated from the live doc model, so it can't drift from the human reference. The same model also serves a public, auth-free, gate-free reference an agent can fetch cold: `GET /api/docs` is the llms.txt index of every service, and `GET /api/docs/{service}` (search, content, answers, research, monitors) is that service's full Markdown spec. The work order embeds a snapshot plus that canonical URL, so the agent can always confirm it has the latest contract.

## Related

- Authentication — https://stelq.com/docs/authentication
- Billing & credits — https://stelq.com/docs/billing-credits
- Research lifecycle & idempotency — https://stelq.com/docs/research-lifecycle-idempotency
- Platform overview — https://stelq.com/docs/platform-overview
- Research service docs — https://stelq.com/docs/api/research
- Search service docs — https://stelq.com/docs/api/search

---
Source: STELQ Documentation. https://stelq.com/docs/agent-mcp-connect

## 3. Full endpoint reference

Every tool maps 1:1 to a REST route. The complete, always-current reference for all services is one public file: https://stelq.com/api/docs/llms-full.txt
Per service:
- Search — `POST /v1/search/query` ($0.001/query): https://stelq.com/api/docs/search
- Content — `POST /v1/content/extract` ($0.002/page): https://stelq.com/api/docs/content
- Research — `POST /v1/research/run` (from $0.08 (by depth)/job): https://stelq.com/api/docs/research
- Answers — `POST /v1/answers/ask` ($0.002/answer): https://stelq.com/api/docs/answers
- Monitors — `POST /v1/monitors/create` ($0.05/monitor per block of 12 queries, then $0.01 per check per block): https://stelq.com/api/docs/monitors

This bundle was generated from STELQ's live doc model. MCP docs URL: https://stelq.com/api/docs/mcp