> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Integrate TinyFish Web Agent with your AI assistant

Connect TinyFish to Claude, Codex, Cursor, ChatGPT, or any MCP-compatible AI assistant. Once connected, your assistant can search the web, browse websites, and extract data on your behalf.

## Quick Install

<Tabs>
  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add tinyfish --url https://agent.tinyfish.ai/mcp
    ```
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code
    ```
  </Tab>

  <Tab title="Claude Desktop">
    ```bash theme={null}
    npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude
    ```
  </Tab>

  <Tab title="ChatGPT">
    Add TinyFish as a custom MCP connector in ChatGPT with this server URL:

    ```text theme={null}
    https://agent.tinyfish.ai/mcp/chatgpt
    ```
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client cursor
    ```
  </Tab>

  <Tab title="Windsurf">
    ```bash theme={null}
    npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client windsurf
    ```
  </Tab>
</Tabs>

<Accordion title="Manual configuration" icon="gear">
  <Tabs>
    <Tab title="Codex">
      ```bash theme={null}
      codex mcp add tinyfish --url https://agent.tinyfish.ai/mcp
      ```
    </Tab>

    <Tab title="Claude Code">
      ```bash theme={null}
      claude mcp add --transport http tinyfish https://agent.tinyfish.ai/mcp
      ```
    </Tab>

    <Tab title="Claude Desktop">
      Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

      ```json theme={null}
      {
        "mcpServers": {
          "tinyfish": {
            "url": "https://agent.tinyfish.ai/mcp"
          }
        }
      }
      ```

      Restart Claude Desktop. You'll be prompted to authenticate via OAuth.
    </Tab>

    <Tab title="ChatGPT">
      Add a custom MCP connector in ChatGPT with:

      ```text theme={null}
      https://agent.tinyfish.ai/mcp/chatgpt
      ```

      ChatGPT will prompt you to authenticate via OAuth.
    </Tab>

    <Tab title="Cursor">
      Add to your Cursor MCP settings:

      ```json theme={null}
      {
        "mcpServers": {
          "tinyfish": {
            "url": "https://agent.tinyfish.ai/mcp"
          }
        }
      }
      ```
    </Tab>

    <Tab title="Windsurf">
      Add to `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows):

      ```json theme={null}
      {
        "mcpServers": {
          "tinyfish": {
            "serverUrl": "https://agent.tinyfish.ai/mcp"
          }
        }
      }
      ```
    </Tab>
  </Tabs>
</Accordion>

## Available Tools

### Web Automation

* **`run_web_automation`** — Execute multi-step web automation given a URL and natural language goal. Streams progress in real-time. Use this for tasks that require clicking, navigating, filling forms, logging in, or interacting with a website. For authenticated recurring workflows, pass `use_profile: true`; add `profile_id` to select a specific Browser Context Profile.
* **`run_web_automation_async`** — Same as `run_web_automation` but returns a `run_id` immediately without waiting. Use for long-running tasks where you don't need real-time progress. Poll with `get_run`. Supports the same `use_profile`, `profile_id`, and `use_vault` controls.
* **`get_run`** — Retrieve details of a specific automation run by ID. Returns status, result, and error info.
* **`list_runs`** — List your automation runs with optional filtering by status and pagination.
* **`cancel_run`** — Cancel a running or pending automation run by ID. Idempotent — already-terminal runs return their current status.

### Batch Automation

* **`batch_create`** — Start multiple web automations simultaneously (up to 8). Each run opens its own browser session. Returns all run IDs immediately.
* **`batch_status`** — Check the status of multiple runs at once (up to 8). Poll every 30–60 seconds until `all_terminal` is true.
* **`batch_cancel`** — Cancel multiple running or pending runs by their IDs (up to 8). Idempotent.

### Web Search

* **`search`** — Search the web and get structured results with titles, snippets, and URLs. Use this to find information or discover URLs before automating a specific site. Optional filters: `recency_minutes`, `after_date`, `before_date`, `domain_type` (`"web"` | `"news"` | `"research_paper"`), `pub_year_min` / `pub_year_max`. When `domain_type=research_paper`, `recency_minutes`, `after_date`, and `before_date` are not supported — use `pub_year_min` / `pub_year_max` instead to scope by publication year (inclusive integers, `0`-`9999`, with `pub_year_min <= pub_year_max` when both are set). You can also pass an optional `purpose` — a short statement of why you're searching — to give the search additional intent signal for better-quality results.
* **`run_big_search`** — Deep, multi-source web research when a simple search isn't enough. Returns a `session_id` immediately; poll with `get_search_result`. Modes: `quick` (\~2 min), `standard` (\~5 min, default), `deep` (\~15 min). Supports the same optional search filters: `recency_minutes`, `after_date`, `before_date`, `domain_type` (`"web"` | `"news"` | `"research_paper"`). When `domain_type=research_paper`, date and freshness filters are not supported. `pub_year_min` / `pub_year_max` are **not** supported here — use the `search` tool for publication-year filtering.
* **`get_search_result`** — Poll a research session by `session_id` to retrieve the result once it's ready.
* **`get_search_usage`** — List past search usage records with filtering by date range and status.

### Content Extraction

* **`fetch_content`** — Fetch web pages, render JavaScript-heavy pages when needed, and extract clean, structured content. Preferred over `run_web_automation` when you only need to read page content. Supports up to 10 URLs per request. You can also pass an optional `purpose` — a short statement of why you're fetching the URLs — to give the fetch additional intent signal for better-quality results.
* **`list_fetch_usage`** — List past fetch requests with filtering by date range and status. Returns metadata only.

### Browser Sessions

* **`create_browser_session`** — Create a remote, stealth Chrome browser session and get CDP connection details. Use for direct programmatic browser control with Playwright, Puppeteer, or Selenium.
* **`list_browser_sessions`** — List your browser sessions with optional filtering by session ID, time range, and status.

## Profile-Aware Automation

Browser Context Profiles let MCP automation reuse saved login state. If the user asks for an authenticated or recurring workflow, prefer a saved profile instead of logging in from scratch every run. Use `run_web_automation` with `use_profile: true`. If the user provides a profile ID, pass it as `profile_id`; `profile_id` requires `use_profile: true`. Pair with `use_vault: true` when the run should repair stale sessions with saved credentials.

```json theme={null}
{
  "url": "https://app.example.com/dashboard",
  "goal": "Summarize the account health dashboard",
  "use_profile": true,
  "use_vault": true
}
```

```json theme={null}
{
  "url": "https://app.example.com/dashboard",
  "goal": "Download the latest invoice",
  "use_profile": true,
  "profile_id": "prof_abc123def4567890"
}
```

Create and save profiles from the [Browser Context Profiles API](/agent-api/browser-context-profiles) or dashboard before using them from MCP. API setup returns a `cdp_url` for Playwright/Puppeteer/CDP and a `base_url` for TinyFish HTTP session endpoints such as `/pages`. Browser Context Profiles are saved session state; [Browser Profiles](/key-concepts/browser-profiles) are the `browser_profile: "lite" | "stealth"` runtime modes.

## Example Usage

```
"Go to https://example.com and extract the product prices"

"Use my saved Salesforce profile to summarize the dashboard"

"Search for the best Italian restaurants in San Francisco"

"Scrape the pricing pages from these 5 competitor websites at the same time"

"Fetch https://docs.stripe.com/api/charges and summarize the API parameters"

"Create a browser session on https://example.com so I can control it with Playwright"
```

## Credit Costs

| Tool                     | Rate                         |
| ------------------------ | ---------------------------- |
| `run_web_automation`     | 1 credit per run step        |
| `search`                 | Free for all users           |
| `fetch_content`          | Free for all users           |
| `create_browser_session` | 1 credit = 4 browser-minutes |

## Authentication

TinyFish MCP uses OAuth 2.1 for secure authentication. The first time you connect, your browser will open to complete the OAuth flow.

### Before You Start

Make sure you are signed in to both of these in your **default browser** before triggering the OAuth flow:

1. [claude.ai](https://claude.ai) — your Claude/Anthropic account
2. [agent.tinyfish.ai](https://agent.tinyfish.ai) — your TinyFish account

### Authentication Flow

When you first configure the TinyFish MCP server, Claude Desktop will open your default browser to complete OAuth. Since you're already signed in to both services, the flow will redirect automatically and complete without manual input.

<Note>You need a TinyFish account with an active subscription or credits. [Sign up here](https://agent.tinyfish.ai/api-keys).</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tool not showing up" icon="circle-question">
    1. Restart your AI client after adding the config
    2. Check that the config JSON is valid
    3. Ensure you're authenticated (OAuth prompt should appear)
  </Accordion>

  <Accordion title="Authentication failing" icon="lock">
    **Before starting the OAuth flow**, make sure you are already signed in to both services in your default browser:

    1. Open your default browser and sign in to [claude.ai](https://claude.ai)
    2. In the same browser, sign in to [agent.tinyfish.ai](https://agent.tinyfish.ai)
    3. Then restart Claude Desktop and trigger the OAuth flow again

    The OAuth redirect will open in your default browser. If you're not already signed in there, the flow will fail or get stuck.

    **Still not working?**

    * **Clear cookies** - Clear browser cookies for both claude.ai and agent.tinyfish.ai, then retry
    * **Check TinyFish account** - Verify your account is active at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys)
  </Accordion>

  <Accordion title="Server disconnected (Windows)" icon="windows">
    On Windows, if you see "Server disconnected" errors:

    1. **Close Claude Desktop completely** - Check Task Manager and end any Claude processes
    2. **Use the direct URL method** - The recommended setup using `"url": "https://agent.tinyfish.ai/mcp"` in your config avoids these issues entirely (see Quick Install above)
    3. **Complete OAuth quickly** - When the browser opens, complete the sign-in promptly to avoid timeout issues
  </Accordion>

  <Accordion title="Automation timing out" icon="clock">
    Complex automations may take 30-60 seconds. For sites with bot protection, the assistant should use `browser_profile: "stealth"`.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quick-start">
    Get started with the REST API
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full endpoint documentation
  </Card>
</CardGroup>