# Wayfern MCP

Connect an AI agent to Wayfern's remote Model Context Protocol server.

## Endpoint

`https://api.wayfern.com/mcp`

- Transport: Streamable HTTP
- Authentication: `Authorization: Bearer wf_...`
- Required token scope: `mcp`
- Access: an active paid plan or positive credit balance (service accounts are also allowed)
- Protocol: `2026-07-28`, stateless — every request carries its own version and capabilities
- Also served: the `initialize` handshake and `Mcp-Session-Id` sessions used by `2025-11-25` and earlier clients

### Protocol versions

The endpoint is dual-era, so you do not need to know which revision your client speaks.

- **`2026-07-28` (current)** — stateless. There is no `initialize` call and no session header. Each request declares `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities` in `params._meta`, and mirrors the version and method into the `MCP-Protocol-Version` and `Mcp-Method` headers; `tools/call`, `prompts/get` and `resources/read` also send `Mcp-Name`. Call `server/discover` to read the server's versions, capabilities and instructions in one request. Only POST is accepted.
- **`2025-11-25` and earlier** — the original handshake. Send `initialize`, then pass the returned `Mcp-Session-Id` on every later request and `DELETE` it when done. Still fully supported, because current MCP SDKs implement this revision.

Tokens created before MCP support do not automatically gain the `mcp` scope. Create a new token in the dashboard or mint one with `"scopes": ["mcp"]`.

## Client configuration

```json
{
  "mcpServers": {
    "wayfern": {
      "type": "http",
      "url": "https://api.wayfern.com/mcp",
      "headers": {
        "Authorization": "Bearer ${WAYFERN_API_TOKEN}"
      }
    }
  }
}
```

Set `WAYFERN_API_TOKEN` to the one-time `wf_...` secret. Use your client's secure environment-variable or secret storage support rather than committing the token.

## Search tools

| Tool | Cost | Description |
| --- | --- | --- |
| `search_web` | 2 credits / provider page | Search Google, Bing, and DuckDuckGo. Returns ranked results, ads, provider failures, pagination, and related queries. |
| `list_search_engines` | Free | List live provider ids and labels. |

### search_web inputs

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string | required | Search phrase (1-512 characters). |
| `engines` | string[] | ["google"] | Any of google, bing, duckduckgo. |
| `language` | string | - | Language hint such as en or en-US. |
| `region` | string | - | Market hint such as US. |
| `date` | string | - | Date range in YYYYMMDD..YYYYMMDD form. |
| `filetype` | string | - | Restrict results to a file type such as pdf. |
| `site` | string | - | Restrict results to a domain. |
| `limit` | integer | 50 | Results per provider, from 1 to 200. |
| `start` | integer | 0 | Pagination offset. |
| `filter_duplicates` | boolean | true | Hide near-duplicate results. |
| `include_related` | boolean | true | Return people-also-search features. |

## Web Data tools

| Tool | Cost | Description |
| --- | --- | --- |
| `scrape_page` | 1 credit / page | Fetch one page through an anti-detect browser and return clean markdown, HTML, links and metadata. The screenshot, pdf and json formats add +4 credits (once); summary adds +2. |
| `extract_data` | 1 credit / uncached source page | Extract structured data from one or more pages with a prompt and an optional JSON Schema. Re-running over pages already fetched is free. |
| `map_site` | 2 credits / 10 URLs | List a site's URLs from its sitemaps and page links. |
| `capture_screenshot` | 5 credits / capture | Capture a clean image of a page — cookie banners dismissed, lazy images loaded, tall pages captured end to end. Returns a downloadable URL. |
| `brand_profile` | 10 credits / profile | Identity, colours, logos, social links and company metadata for a domain. |
| `site_styleguide` | 10 credits / site | Colours, typography, spacing, radii, shadows and the design tokens a site declares. |
| `site_fonts` | 5 credits / site | Font families, where each is served from, available weights, file formats and where they are used. |
| `crawl_site` | 1 credit / successful page | Start a bounded multi-page crawl. Returns a job id immediately and charges nothing up front; pages are billed as the crawl runs. |
| `crawl_status` | Free | Poll a crawl started with crawl_site and read a page of its results. The pages were billed as they were crawled. |

The Web Data tools call the same services as the REST endpoints, so results and billing are identical. They expose a deliberately smaller surface: crawl_site takes no webhook (poll it with crawl_status), always loads the site's robots.txt and honours the crawl-delay it declares, stays on the starting site, and runs 3 pages in parallel with no extra delay. For custom headers, per-page cache control, PDF paper sizes, path-pattern crawls with webhooks, or the styleguide/fonts reports at a custom timeout, call the REST API at https://api.wayfern.com/api/v1 with a token carrying the `web` scope.

### scrape_page inputs

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | string | required | The page to scrape (1-2048 characters). |
| `formats` | string[] | ["markdown"] | 1-8 of markdown, html, rawHtml, links, screenshot, pdf, json, summary. |
| `only_main_content` | boolean | true | Strip navigation, headers and footers. |
| `wait_for_ms` | integer | 0 | Milliseconds to wait after load, 0-30000. |
| `proxy` | string | "auto" | auto, datacenter, or residential. |
| `country` | string | - | ISO-3166 alpha-2 exit country, exactly two characters. |
| `summary_prompt` | string | - | Instruction for the summary format. Max 2000 characters. |
| `json_prompt` | string | - | What the json format should extract. Max 2000 characters. |

### extract_data inputs

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `urls` | string[] | required | 1-100 URLs. A trailing /* expands to that path's discovered URLs, billed as a map call. |
| `prompt` | string | required | What to extract, 1-4000 characters. |
| `schema` | object | - | JSON Schema the result must conform to. |
| `max_pages` | integer | 10 | Ceiling on source pages fetched, 1-100. |
| `proxy` | string | "auto" | auto, datacenter, or residential. |

### map_site inputs

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | string | required | The site to map. |
| `search` | string | - | Keep only URLs matching this term. Max 256 characters. |
| `limit` | integer | 100 | Maximum URLs to return, 1-5000. Billed per block of 10. |
| `include_subdomains` | boolean | false | Include URLs on subdomains. |

### capture_screenshot inputs

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | string | required | The page to capture. |
| `full_page` | boolean | true | Capture the whole scrollable page. |
| `format` | string | "png" | png or jpeg. |
| `dark_mode` | boolean | false | Render in dark mode. |
| `width` | integer | 1440 | Viewport width in CSS pixels, 320-3840. |
| `height` | integer | 900 | Viewport height in CSS pixels, 320-3840. |
| `proxy` | string | "auto" | auto, datacenter, or residential. |

### brand_profile, site_styleguide, site_fonts inputs

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | string | required | The site to analyse. |
| `proxy` | string | "auto" | auto, datacenter, or residential. |

### crawl_site inputs

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `url` | string | required | The URL the crawl starts from. |
| `limit` | integer | 50 | Maximum pages to scrape, 1-5000. Each success is 1 credit. |
| `max_depth` | integer | 3 | Link hops to follow from the start URL, 0-10. |
| `include_paths` | string[] | - | Regular expressions a path must match. Up to 50, each max 512 characters. |
| `exclude_paths` | string[] | - | Regular expressions that exclude a path. Up to 50. |
| `allow_subdomains` | boolean | false | Follow links onto subdomains. |
| `formats` | string[] | ["markdown"] | Per-page output formats, as for scrape_page. |

### crawl_status inputs

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `crawl_id` | string | required | The id crawl_site returned, 1-64 characters. |
| `skip` | integer | 0 | Documents to skip. |
| `limit` | integer | 25 | Documents to return, 1-100. |

## Credits

Every tool that fetches from the live web spends credits, at exactly the rates the REST API charges: search_web meters each provider page it fetches (a large limit can fetch several per provider), and the Web Data tools bill per page, per capture, per site or per block of 10 URLs as listed above. list_search_engines, crawl_status, resources, and prompts are free. Every tool result reports what it actually cost in credits_charged, and credits come from one shared account balance that browser sessions, captcha solves, and residential egress draw on too.

## Resources and prompt

- `wayfern://search-engines` — current provider catalog as JSON.
- `wayfern://mcp/help` — concise MCP usage and billing notes.
- `research_with_wayfern` — reusable multi-source research prompt.

## Raw request (2026-07-28)

```bash
curl -X POST https://api.wayfern.com/mcp \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": { "name": "my-agent", "version": "1.0.0" }
      }
    }
  }'
```

## Raw initialize request (2025-11-25 and earlier)

```bash
curl -X POST https://api.wayfern.com/mcp \
  -H "Authorization: Bearer wf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0.0" }
    }
  }'
```

Normal MCP clients handle version negotiation, per-request metadata, and — on older revisions — initialization and session-header management automatically.