MCP

MCP search tool

Search the web with Yep and get ranked results.

The tool takes the same arguments as the body of a REST search request and returns the same response: POST /api/v1/search

At a glance

search tool facts
Name	Value
Tool	search
OAuth scopes	search:read
Billing	Billed as one search when the call completes.
Behavior	Read-only, non-destructive, and idempotent.

Try it

Ask your agent: Search the web with Yep for the latest news about carbon border taxes, and list five sources.

Example call

The agent sends the call as a JSON-RPC tools/call request:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "carbon border tax 2026",
      "limit": 5
    }
  }
}

A successful call returns the response in structuredContent. Its required fields have this shape:

json

{
  "request_id": "string",
  "duration_ms": 0,
  "select": [
    "url"
  ],
  "results": [
    {
      "rank": 0,
      "fields": {}
    }
  ]
}

Input

query string Required
The search text.
Minimum length
- 1
Maximum length
- 512
limit integer | null Optional
The maximum number of results. The default is 20.
Minimum
- 1
Maximum
- 50
lang string | null Optional
A two-letter lowercase language code that results must match.
Pattern
- ^[a-z]{2}$
ranking SearchRanking | null Optional
What the ranking favors. The default is balanced.
Allowed
- precision
- balanced
- authority
- content_gap
select SearchResultField[] Optional
The fields each result returns.
Default
- ["url","title","description","language"]
Minimum items
- 1
filter string | null Optional
An expression in the filter language that every result must satisfy.
Minimum length
- 1
Maximum length
- 65536
max_results_per_domain integer | null Optional
The maximum number of results from one registrable domain.
Minimum
- 1
Maximum
- 10

The filter language and every field a result can return: Filters and fields

Output

request_id string Required

The reference of the request, to quote when contacting support.
duration_ms integer Required
The time taken to answer, in milliseconds.
Minimum
- 0
select SearchResultField[] Required

The fields each result returns, after the default is applied.
results ProjectedPageResult[] Required

The results, best first.

Tool errors

A failed call sets isError and returns a structured error: Tool errors

MCP server Search with typed filters and result projection