MCP

Desearch MCP is available over hosted Streamable HTTP. Create an API key in Console, then add the server in your agent.

Endpoint: https://mcp.desearch.ai/mcp
Auth for tool calls: Authorization: Bearer <DESEARCH_API_KEY> or x-api-key: <DESEARCH_API_KEY>

Discovery without a key is allowed: initialize and tools/list return successfully with no API key. Calling a tool (tools/call) without a key returns 401 (-32001). Preferred client config examples below still show a key on every request so tools/call works after connect; some clients accept a raw key in Authorization (no Bearer prefix). Do not claim OAuth on this host.

Choose your client

Client	Transport to document now	Notes
Claude Code	Hosted HTTP	CLI add with HTTP transport
Cursor	Hosted HTTP	`mcp.json` url + headers
VS Code	Hosted HTTP	use `servers` key (not `mcpServers`)
Claude Desktop	Hosted HTTP if the client supports URL servers	Do not claim npm works
Codex / other	Hosted HTTP generic shape	Match client docs for custom headers
npm / stdio	Not documented as working yet	Local install stays out of this page

Claude Code (hosted HTTP)

bash

claude mcp add --transport http desearch https://mcp.desearch.ai/mcp \
  --header "Authorization: ${DESEARCH_API_KEY}"

If your CLI build expects a different header flag, use the equivalent custom-header option and keep the same key value.

Cursor (`~/.cursor/mcp.json`)

json

{
  "mcpServers": {
    "desearch": {
      "url": "https://mcp.desearch.ai/mcp",
      "headers": {
        "Authorization": "<DESEARCH_API_KEY>"
      }
    }
  }
}

VS Code (user `mcp.json` / servers)

json

{
  "servers": {
    "desearch": {
      "type": "http",
      "url": "https://mcp.desearch.ai/mcp",
      "headers": {
        "Authorization": "<DESEARCH_API_KEY>"
      }
    }
  }
}

Generic HTTP shape

json

{
  "url": "https://mcp.desearch.ai/mcp",
  "headers": {
    "Authorization": "<DESEARCH_API_KEY>"
  }
}

Verify

Restart or reload the MCP session in the client.
Confirm the Desearch server shows as connected.
Confirm tools appear from live tools/list. Inventory can change. Do not hard-code a tool count.
Call a simple tool such as web-search with {"query":"desearch"} or ai-search with {"prompt":"desearch docs"}.

Health (operators)

GET https://mcp.desearch.ai/health returns 200 JSON when the host is up (ok, version, transport, endpoint, and an auth string that states initialize / tools/list are public and tools/call needs a key). GET https://mcp.desearch.ai/api/health returns the same body. This is a probe only; it is not a substitute for a keyed tools/call.

Troubleshoot

Symptom	Check
401 / unauthorized on `tools/call`	Send `Authorization: Bearer <key>` or `x-api-key`; discovery (`initialize` / `tools/list`) does not need a key
Server missing	Config path for that client; restart client
Tools list empty	Network to `mcp.desearch.ai`; key scope
npm install failures	Out of scope here; hosted HTTP is the documented path

npm / stdio

Local npm and stdio install instructions stay out of this page until a works smoke is signed. Do not paste npx desearch-mcp-server as a proven default.

Keys are created in Console. See Auth and API keys.

Tools available on the host

Snapshot from live keyless tools/list (2026-10-05, host 0.1.4). Always prefer your client's live tools/list. Inventory and titles can change; do not hard-code a tool count as permanent.

#	Tool	Title	Docs depth now
1	`ai-search`	AI Search	Deep example
2	`x-search`	X Search	Deep example
3	`web-search`	Web Search	Deep example
4	`web-links-search`	Web Links Search	Full example
5	`x-links-search`	X Links Search	Deep example
6	`x-posts-by-urls`	Get X Posts by URLs	Name + arg hint
7	`x-post-by-id`	Get X Post by ID	Name + arg hint
8	`x-posts-by-user`	Search X Posts by User	Name + arg hint (`user`)
9	`x-post-retweeters`	List X Post Retweeters	Name + arg hint
10	`x-user-posts`	Get X User Timeline	Name + arg hint (`username`)
11	`x-user-replies`	Get X User Replies	Name + arg hint (`user`)
12	`x-post-replies`	Get X Post Replies	Name + arg hint (`post_id`)
13	`extract`	Extract Page Content	Deep example
14	`web-crawl`	Crawl Web Page (Legacy)	Deep example
15	`x-trends`	Get X Trends	Full example

Example: `ai-search`

Required field is prompt (not query).

Optional tools uses short ids (mcp-desearch #18; host 0.1.4). Teach web and twitter in examples. Schema default when omitted: ["web", "twitter"]. Do not send youtube (removed from AI Search; not in live ai-search enum). Legacy alias ids such as reddit, arxiv, wikipedia, and hackernews remain in the live enum and are accepted as aliases; do not document them as the preferred set, and do not claim the MCP enum is exactly ["web", "twitter"]. Legacy display labels such as Web Search or Twitter Search are still accepted and rewritten to short ids. Prefer short ids in new examples.

json

{
  "name": "ai-search",
  "arguments": {
    "prompt": "latest AI search API notes",
    "result_type": "LINKS_WITH_FINAL_SUMMARY",
    "tools": ["web", "twitter"],
    "model": "NOVA"
  }
}

Expected shape when result_type is LINKS_WITH_FINAL_SUMMARY: search results with HTTP links, a completion/summary field, and usage/cost fields. When tools includes both web and twitter, a successful call can also include a tweets array of X posts in the same JSON body alongside search. An empty search or tweets array (or a tool_no_results warning) means that tool finished with no hits. Do not assume both arrays are always filled on every SUMMARY call. result_type: ONLY_LINKS returns a JSON object with a search array of link objects (title, link, snippet, highlights) and no completion. An empty search array means the search finished with no hits.

Example: `x-search`

json

{
  "name": "x-search",
  "arguments": {
    "query": "desearch",
    "count": 3
  }
}

Expected shape when the call succeeds: post payloads (not a crash on legacy method names).

Example: `web-search`

json

{
  "name": "web-search",
  "arguments": {
    "query": "desearch web search API"
  }
}

Expected shape when the call succeeds: a data array of link results.

Example: `x-links-search`

json

{
  "name": "x-links-search",
  "arguments": {
    "prompt": "desearch",
    "count": 10
  }
}

Use count of at least 10 when you set it. Expected shape includes miner tweet payloads when the call succeeds.

Examples: `extract` and `web-crawl`

json

{
  "name": "extract",
  "arguments": {
    "url": "https://www.desearch.ai",
    "format": "text"
  }
}

json

{
  "name": "web-crawl",
  "arguments": {
    "url": "https://www.desearch.ai",
    "format": "text"
  }
}

Example: `web-links-search`

Live schema expects prompt plus tools. The only accepted short id is web (default ["web"]). Other short ids are rejected. If you set count, send an integer from 10 to 200.

json

{
  "name": "web-links-search",
  "arguments": {
    "prompt": "open source browser automation tools",
    "tools": ["web"],
    "count": 10
  }
}

Expected shape when the call succeeds: a JSON object with search_results, a list of link objects. On the 2026-10-01 hosted check each item had title, link, snippet, highlights, and published_date. An empty list means the search finished with no hits. This tool does not search X. For X post links use x-links-search.

Truncated item (placeholders, not a live URL):

json

{
  "search_results": [
    {
      "title": "Example result",
      "link": "https://example.com/result",
      "snippet": "Short source text.",
      "highlights": ["Short source text."],
      "published_date": "2026-10-01T00:00:00"
    }
  ]
}

Other X tools (name + arg hints)

Follow live tool schemas. Smoke-checked argument names:

Tool	Arg hints
`x-posts-by-urls`	URL list per live schema
`x-post-by-id`	post id
`x-posts-by-user`	`user`
`x-post-retweeters`	post id (empty users list can be valid)
`x-user-posts`	`username`
`x-user-replies`	`user`
`x-post-replies`	`post_id` (empty array can be valid)

Example: `x-trends`

Hosted MCP still lists x-trends. Schema (smoke): required woeid; optional count in 30–100.

json

{
  "name": "x-trends",
  "arguments": {
    "woeid": 23424977,
    "count": 30
  }
}

Successful tool result is a JSON object with a trends array (name / query / rank), plus location metadata. Do not pass count below 30.

Connect

Connect over MCP (hosted HTTP) with your Desearch API key.
Endpoint: https://mcp.desearch.ai/mcp.
See live tools/list for the current tool inventory.

Choose your client

Claude Code (hosted HTTP)

Cursor (~/.cursor/mcp.json)

VS Code (user mcp.json / servers)

Generic HTTP shape

Verify

Health (operators)

Troubleshoot

npm / stdio

Tools available on the host

Example: ai-search

Example: x-search

Example: web-search

Example: x-links-search

Examples: extract and web-crawl

Example: web-links-search

Other X tools (name + arg hints)

Example: x-trends

Connect

Cursor (`~/.cursor/mcp.json`)

VS Code (user `mcp.json` / servers)

Example: `ai-search`

Example: `x-search`

Example: `web-search`

Example: `x-links-search`

Examples: `extract` and `web-crawl`

Example: `web-links-search`

Example: `x-trends`