# Web Search — how to use (mcp.ai)

Search the web and read the pages that matter, all from your agent. Returns organic results with title, link and snippet, extracts clean text from any URL and shows how people actually search for a topic. Accepts up to 100 queries in a single call. Hosted by the platform, no credentials, you pay per query.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_web_search?ms=1788152100000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `web_search_read_page`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/web_search`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/web_search/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/web_search/read/page` — Lê uma página da web e devolve o texto limpo mais os metadados dela. Use depois de uma busca, para abrir os links que interessaram. Custa o dobro de uma busca por URL. Aceita até 100 URLs por chamada.
  - body: { urls: string[], markdown?: boolean }
- `POST https://api.mcp.ai/api/web_search/search` — Busca na web e devolve os resultados orgânicos com título, link e trecho, mais a resposta direta e o painel de conhecimento quando existem. Aceita até 100 consultas por chamada.
  - body: { consultas: string[], pais?: string, idioma?: string, limite?: integer, periodo?: string, local?: string, pagina?: integer }
- `POST https://api.mcp.ai/api/web_search/suggest` — Devolve as sugestões de autocompletar para um termo. Serve para descobrir como as pessoas realmente pesquisam um assunto, útil em SEO e pesquisa de mercado. Aceita até 100 termos por chamada.
  - body: { consultas: string[], pais?: string, idioma?: string }

## Example prompts
- "Search "best CRMs 2026", open the top 3 results and compare them"
- "How do people search for open finance? Show me the search suggestions"
- "Read this page and summarize the main points for me"

## More
- Page: https://mcp.ai/web_search
- Agent spec (llms.txt): https://mcp.ai/web_search/llms.txt
- Postman collection: https://mcp.ai/web_search/postman.json