# MCP server
> Give Claude, Cursor, VS Code or any MCP client live web access with a hosted Search1API MCP endpoint — no code required.
Canonical URL: https://s1.dev/docs/integrations/mcp
Search1API runs a hosted MCP server at:
```
https://mcp.search1api.com/mcp
```
Point an OAuth-aware MCP client at it and Search1API will advertise the authorization flow automatically. Clients that do not support OAuth discovery can continue using an API key. Either way, the model can search the web, read pages and check what's trending without you writing an integration.
## Tools it exposes
| Tool | What it does | Required |
| --- | --- | --- |
| `search` | Web search | `query` |
| `news` | News search | `query` |
| `ask` | Describe what you need; Search1API picks the engines and time window | `query` |
| `maps` | Google Maps places: name, address, phone, website, rating, coordinates, opening hours (3 credits per page of up to 20 places) | `query` |
| `crawl` | Read a URL | `url` |
| `sitemap` | List a site's links | `url` |
| `deepcrawl` | Read many pages of one site, such as a docs section (20 credits per started task) | `url`, or `task_id` to collect a running task |
| `trending` | GitHub / Hacker News trends | `search_service` |
| `render_results` | Present selected existing sources as cards or a readable list; no search credits | `results` |
| `send_feedback` | Report a wrong result, an unresolved error, or a missing capability to the Search1API team; no credits | `message` |
## Crawl a site
`deepcrawl` (added in 0.11.0) starts a [deepcrawl](https://s1.dev/docs/advanced/deepcrawl) task with JSON results and returns the pages as citable results with title, URL, and Markdown text, plus page counts and the URLs that failed.
- Inputs: `url`, `max_pages` (default 10, at most 50), `include_paths`, `exclude_paths`, `type` (`sitemap` or `all`), and `task_id`.
- It waits about 45 seconds. If the crawl is still running, the result holds a `task_id`; calling `deepcrawl` again with that `task_id` collects the pages without starting a new task and costs no credits.
- Page text is capped at 8,000 characters per page and 80,000 in total. When text is cut, `result_url` points to the full JSON result.
- Each started task costs 20 credits, however many pages it reads.
## Display selected sources
The remote endpoint and `search1api-mcp` 0.8.0+ over stdio expose `render_results` alongside the data tools. Keep the same connection URL:
```text
https://mcp.search1api.com/mcp
```
`search`, `news` and `ask` retrieve results without automatically displaying cards. When a source list helps the task, the model can select, combine and pass existing results to `render_results`:
```json
{
"title": "Selected sources",
"results": [
{
"id": "https://s1.dev/docs",
"title": "Search1API documentation",
"url": "https://s1.dev/docs"
}
]
}
```
`results` is required and accepts 0–50 entries. Each entry requires `title` and an HTTP(S) `url`; `id`, a source snippet in `text` (up to 2,000 characters), and original `metadata` are optional. The list `title` is optional and defaults to `Results`. Preserve original source titles and links. Whole crawled pages are not needed to draw cards.
The tool returns `structuredContent` with `title`, `total`, and `results`, plus a complete readable source list in `content`. MCP Apps clients can display the cards; clients without UI or structured-output support still receive the titles, links and snippets as text. An empty list succeeds with “No results to display.”
Rendering and expanding cards do not search, fetch pages or consume search credits. A successful tool response confirms that results were prepared, not that the host displayed them. Ordinary cited answers and intermediate research do not require a rendering call.
There is no UI URL parameter to configure. Keep existing OAuth or API-key authentication, and reconnect or refresh tool discovery if `render_results` is missing. Both transports return the same structured JSON and text list; the client decides whether to load the UI. Source-card display has been verified in ChatGPT desktop and Claude web, desktop and mobile. UI availability depends on the host and its version. Directory connections may need host review before newly added tools appear. For local stdio, upgrade to 0.8.0+ and restart the MCP connection.
## Connect your client
### Claude directory (recommended for Claude)
Search1API is published as both a connector and a plugin. Both use this hosted MCP server and the same hosted tools; the plugin adds an Agent Skill. See the [Claude guide](https://s1.dev/docs/integrations/claude) for a comparison and installation steps.
- **[Add Search1API connector](https://claude.ai/directory/search1api):** add it to Claude, then sign in with your Search1API account through OAuth. This provides the hosted MCP tools in Claude web, desktop, and mobile.
- **[Install Search1API plugin](https://claude.ai/customize/plugins/id/c73feffb-aae4-49f4-8515-24322b313989%40anthropic-plugin-directory):** add the plugin, then connect Search1API. It bundles the same MCP tools with an Agent Skill and supports Claude apps, Cowork, and Claude Code. Plugins require a paid Claude plan.
Plugins added to your Claude account sync to Claude Code v2.1.273 or later when signed in with the same account. For a direct MCP connection in Claude Code instead:
```bash
claude mcp add --transport http search1api https://mcp.search1api.com/mcp
```
Run `/mcp` in Claude Code and sign in when prompted. Use the API-key fallback below if you prefer an API key.
### OAuth 2.1 (preferred)
For a client that supports OAuth discovery, start with the endpoint only:
```json
{
"mcpServers": {
"search1api": {
"url": "https://mcp.search1api.com/mcp"
}
}
}
```
The exact outer configuration key varies by client, but the server URL is the same. On the first connection, the server returns a `WWW-Authenticate` challenge pointing to:
```
https://mcp.search1api.com/.well-known/oauth-protected-resource/mcp
```
The client can then discover Search1API's authorization server, dynamically register, and use Authorization Code + PKCE. The account owner signs in and approves access in the browser. A client that requests `offline_access` can refresh its access token for long-running sessions.
> **info:** OAuth support depends on the MCP client. If a client does not follow protected-resource discovery, use the API-key configuration below.
### API key fallback
Create a key at [app.s1.dev](https://app.s1.dev), then use the configuration for your client. The dashboard's **MCP** page can generate these examples with the key filled in.
```bash
claude mcp add --transport http search1api https://mcp.search1api.com/mcp \
--header "Authorization: Bearer YOUR_SEARCH1API_KEY"
```
```json
{
"mcpServers": {
"search1api": {
"url": "https://mcp.search1api.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_SEARCH1API_KEY"
}
}
}
}
```
Cursor also has a one-click install and its own `mcp.json` conventions — see [Cursor](https://s1.dev/docs/integrations/cursor).
Note the different key (`servers`, not `mcpServers`) and the required `type`:
```json
{
"servers": {
"search1api": {
"type": "http",
"url": "https://mcp.search1api.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_SEARCH1API_KEY"
}
}
}
}
```
Windsurf passes the key in the URL rather than a header:
```json
{
"mcpServers": {
"search1api": {
"serverUrl": "https://mcp.search1api.com/mcp?apiKey=YOUR_SEARCH1API_KEY"
}
}
}
```
### Install via Smithery (optional)
Prefer a one-click install? Search1API is listed on [Smithery](https://smithery.ai/servers/superagents-lab/search1api-mcp), which supports 20+ MCP clients (Claude Code, Codex, Cursor, Windsurf, Gemini CLI, and more). A [search1api agent skill](https://smithery.ai/skills/superagents-lab/search1api) is also available for hosts that support skills.
## How auth works
The hosted server accepts either an OAuth access token or a Search1API API key in the `Authorization: Bearer ` header. OAuth tokens and API keys use the same Search1API account credits, billing, and rate limits.
When no credential is present, the server returns a `401` challenge with its protected-resource metadata URL. Invalid or expired OAuth tokens return the same challenge with `error="invalid_token"`, allowing a compatible client to refresh or repeat authorization.
For legacy clients that cannot send headers, the server also accepts an API key in the `?apiKey=` query parameter. The header wins when both are present.
Query-parameter auth means your key travels in a URL, where it can end up in logs and shell history. Prefer OAuth or a bearer header whenever the client supports one of them.
## Protocol support
The hosted server implements the Model Context Protocol revision `2026-07-28`, published on 28 July 2026. That revision removes protocol-level sessions and the `initialize` handshake: every request carries its own protocol version and client capabilities in `_meta`, and the server identifies itself in each result.
A request on `2026-07-28` needs two things beyond the ordinary JSON-RPC body:
- an `Mcp-Method` header matching the `method` in the body;
- a `_meta` object carrying `io.modelcontextprotocol/protocolVersion`, `io.modelcontextprotocol/clientInfo`, and `io.modelcontextprotocol/clientCapabilities`.
Call `server/discover` to read the supported versions, capabilities, and server identity before sending anything else:
```bash
curl -sS -X POST https://mcp.search1api.com/mcp \
-H "Authorization: Bearer YOUR_SEARCH1API_KEY" \
-H "Mcp-Method: server/discover" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "server/discover",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" },
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}'
```
It answers with the supported revisions and the server identity:
```json
{
"result": {
"supportedVersions": ["2026-07-28"],
"capabilities": {
"tools": { "listChanged": true },
"resources": { "listChanged": true }
},
"resultType": "complete",
"_meta": {
"io.modelcontextprotocol/serverInfo": {
"name": "search1api-server",
"version": "0.5.1"
}
}
}
}
```
Swap the `Mcp-Method` header and the `method` field for `tools/list` and the same envelope returns the tools above.
> **info:** Clients on the 2025 protocol revisions keep working unchanged. A client that sends `initialize` with `2025-06-18` still receives a normal response over both HTTP and stdio, so nothing you have configured today needs to move.
## Running it locally instead
The server also runs over stdio, straight from npm:
```json
{
"mcpServers": {
"search1api": {
"command": "npx",
"args": ["-y", "search1api-mcp@latest"],
"env": {
"SEARCH1API_KEY": "YOUR_SEARCH1API_KEY"
}
}
}
}
```
Version 0.9.0 includes every tool above, including `send_feedback`, and the bundled MCP Apps view. To upgrade a global installation, run `npm install -g search1api-mcp@latest`; for an `npx` configuration, use `search1api-mcp@latest` as above and restart your client.
The local stdio package uses an API key. There is no network hop to us for the MCP protocol itself, but its API calls still go to `api.search1api.com`.
## Server icon
Both transports advertise the square Search1API logo through standard `serverInfo.icons`. Clients choose whether to display it. The icon is a public 512×512 PNG served from the MCP origin, without authentication.
## Billing
MCP tool calls are ordinary API calls: they spend the same credits at the same rates as calling the endpoints yourself. See [Credits and limits](https://s1.dev/docs/essentials/credits-and-limits).
Source: [github.com/superagents-lab/search1api-mcp](https://github.com/superagents-lab/search1api-mcp)