mcp

<!-- mcp-name: ai.foura/mcp -->
<p align="center">
  <a href="https://foura.ai/mcp"><img src="https://foura.ai/logo/avatars/4a-transparent-indigo-512.png" width="96" alt="FourA"></a>
</p>

<h1 align="center">FourA MCP</h1>

<p align="center"><strong>Reliable web access for AI agents.</strong></p>

<p align="center">
  Give your agent a public URL. FourA returns the content, whether the page needs a fast HTTP request,
  proxy rotation, or a full browser session.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@fouradata/mcp"><img src="https://img.shields.io/npm/v/@fouradata/mcp?logo=npm&color=cb3837" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/@fouradata/mcp"><img src="https://img.shields.io/badge/supply_chain-provenance_signed-2ea44f?logo=npm" alt="npm provenance"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@fouradata/mcp?color=2ea44f" alt="MIT license"></a>
  <a href="https://glama.ai/mcp/servers/fouradata/mcp"><img src="https://glama.ai/mcp/servers/fouradata/mcp/badges/score.svg" alt="FourA MCP score on Glama"></a>
  <a href="https://tdqs.dev/reports/ivgtefqu60"><img src="https://tdqs.dev/reports/ivgtefqu60/badge.svg" alt="Tool Definition Quality Score for FourA MCP"></a>
  <a href="https://smithery.ai/servers/foura/mcp"><img src="https://img.shields.io/badge/Smithery-listed-6e56cf" alt="FourA on Smithery"></a>
</p>

Start with `foura_auto`: one URL in, typed content out. It chooses the appropriate fetch method and handles common blocks for you. Use `foura_single`, `foura_proxy`, or `foura_browser` when you want explicit control over the request path.

| Start simple | Reach difficult pages | Build predictable agent flows |
|---|---|---|
| One default tool for most URLs | HTTP, proxy rotation, and full-browser rendering | Typed outputs, stable error codes, and six ready-made prompts |

The included workflows cover product extraction, article cleanup, price monitoring, endpoint checks, and bulk URL fetching.

Use it from Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, or any MCP client. Run the npm package locally or connect to the hosted Streamable HTTP endpoint with the same FourA API key.

**[Get an API key](https://foura.ai/dashboard/#api-keys) | [Read the MCP docs](https://foura.ai/docs/mcp/server) | [See the package on npm](https://www.npmjs.com/package/@fouradata/mcp)**

**One-click install:**

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=foura&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBmb3VyYWRhdGEvbWNwIl0sImVudiI6eyJGT1VSQV9BUElfS0VZIjoiWU9VUl9GT1VSQV9BUElfS0VZIn19)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522foura%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540fouradata%252Fmcp%2522%255D%252C%2522env%2522%253A%257B%2522FOURA_API_KEY%2522%253A%2522YOUR_FOURA_API_KEY%2522%257D%257D)

Both buttons pre-fill the config with a `YOUR_FOURA_API_KEY` placeholder - replace it with your key. Or by hand: `claude mcp add foura -- npx -y @fouradata/mcp` (set `FOURA_API_KEY` in env first). Full per-client setup below.

## Quick Start - local stdio (recommended for Claude Desktop)

Create or reveal an API key at [foura.ai/dashboard/#api-keys](https://foura.ai/dashboard/#api-keys) (format `pk_live_...`). Then drop this into your MCP client's config:

```json
{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": {
        "FOURA_API_KEY": "pk_live_..."
      }
    }
  }
}
```

> **Claude Desktop gotcha:** fully quit Claude Desktop (`Cmd+Q` on macOS) **before** editing the config file. If the app is still running, it will overwrite your edits with its in-memory config on exit.

The npx command downloads the package on first launch and runs it as a subprocess of your MCP client. No global install needed. The same JSON works across MCP clients; only the config-file location changes:

| Client | Where the config lives |
|---|---|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Code | `claude mcp add foura -- npx -y @fouradata/mcp` (set `FOURA_API_KEY` in env first) |
| Cursor | `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| VS Code (MCP extension) | `.vscode/mcp.json` in your workspace |

Restart the client and `foura_auto`, `foura_single`, `foura_proxy`, `foura_browser` show up in your tool list, plus six prompts under `/prompts`.

## Quick Start - hosted (Streamable HTTP)

If your client supports the Streamable HTTP transport, point it at the hosted endpoint instead of running a local subprocess:

```json
{
  "mcpServers": {
    "foura": {
      "url": "https://mcp.foura.ai/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}
```

For Claude Desktop, use the stdio config above. You can also bridge the hosted endpoint through `mcp-remote`:

```json
{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
    }
  }
}
```

## The Tools

`foura_auto` is the **default** - give it a URL and it returns the content, choosing the fetch method for you. The other three tools give you direct control over HTTP, proxy rotation, and browser rendering.

All four are marked `readOnlyHint: true` and `openWorldHint: true` per the [MCP specification](https://modelcontextprotocol.io/specification). Clients can use those annotations when deciding how to present or approve tool calls.

Every response carries human-readable text (`content`) plus a typed `structuredContent` JSON object validated against the tool's `outputSchema`. Your agent gets a predictable response contract instead of parsing prose.

### `foura_auto` - smart fetch (the default)

Give it a URL and get the content back. Use this first when you don't want to choose between HTTP, proxy rotation, and browser rendering. It handles common bot challenges and keeps the client surface small, with no proxy-attempt tuning required.

```jsonc
{
  "url": "https://example.com",
  // optional: a substring the real page must contain, so auto can tell a
  // real page from a challenge page on protected targets
  "validate": { "data": { "accept": ["Example Domain"] } }
}
```

The client surface is intentionally minimal: `url` (required), plus optional `method`, `headers`, `data`, `validate`, `returnSession` (default `true`), `forceProxy` (default `true`), `timeout_ms` (5000-180000, default 120000), `ignoreProxies`.

`structuredContent` shape: `{status, headers, data, meta, session}`. `meta` is always present - `{rung, solved, attempts, credits}` - so your agent can see how the request completed and how many credits it used. `session` (`{proxy, cookies, userAgent}`) is returned by default for follow-up requests (pass `session.proxy` into the `proxy` field). Send `returnSession: false` to omit it. There is no `total_time` field on auto.

### `foura_single` - fast HTTP

One HTTP request, response back. Use it for static pages, JSON APIs, and server-rendered HTML. `unblocker` defaults to `true`, so the request already carries a full browser header set; set it to `false` for a plain HTTP request.

```jsonc
{
  "method": "GET",
  "url": "https://example.com"
}
```

Supports custom headers, a body, per-stage timeouts, redirect controls, JSON auto-parse, a binary-buffer mode, and built-in response validation (`validate.status.accept`, `validate.data.fail`, and so on). If `foura_single` comes back blocked - status 403/429, a captcha page, challenge response headers, or a known challenge title - try a different browser profile (below), then escalate to `foura_proxy`. Start with `maxTries: 5`; protected targets may need `25-30`. If the page also needs JavaScript to render, pass `foura_proxy`'s returned `proxy` ID to `foura_browser.proxy`.

`structuredContent` shape: `{status, headers, data, total_time, ...}`. When the target ran a bot check, the response also carries `defense`; `defense.solved: false` means the body may be a challenge page rather than the content you asked for.

#### Choosing which browser you present

By default a request presents the latest Google Chrome. Some targets accept one browser and refuse another, so `foura_single` and `foura_proxy` let you pick:

```jsonc
{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}
```

- `browser` - `Chrome`, `Edge`, `Safari`, `Firefox`, or `Tor`.
- `os` - `Windows`, `macOS`, `Android`, or `iOS`. A family name accepts any of its versions; the exact labels in the catalogue narrow further.
- `version` - any version the catalogue lists for that browser. The newest match wins when several fit.
- `profile` - an exact id from the catalogue, when you already have one.

The full catalogue is public at [api.foura.ai/api/profiles](https://api.foura.ai/api/profiles), no key required, and its `default` field names the profile a request gets when you ask for nothing. Selection needs `unblocker` on, which is the default. A combination that does not exist returns an error listing what is available, so a request is never quietly sent as a browser you did not choose.

### `foura_proxy` - rotating proxies with retry

Same target shape as `foura_single`, but routed through rotating proxies with automatic retry on failure. Use it when a direct request is blocked or when the target requires a specific exit country.

```jsonc
{
  "maxTries": 5,
  "exitCountries": ["CZ", "GB"],
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "browser": "Ch