MCP Integration

Integrate TinyFish Web Agent with your AI assistant

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

On ChatGPT, Claude, or Grok? The curated TinyFish plugin bundles these tools with skills and safety rules and installs in one command or tap. This page covers the raw MCP endpoint for any client.

Quick Install

Codex

codex mcp add tinyfish --url https://agent.tinyfish.ai/mcp

Grok

1. Install the plugin

   grok plugin install tinyfish --trust
   
2. Open the MCP server list

   grok /mcps
   
3. Authenticate

   In the /mcps list, find the tinyfish MCP server entry and select Authenticate. Grok opens the OAuth flow in your browser — sign in with your TinyFish account to authorize the connection.

Claude Code

npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code

Claude Desktop

npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude

ChatGPT

Add TinyFish as a custom MCP connector in ChatGPT with this server URL:

https://agent.tinyfish.ai/mcp/chatgpt

Cursor

npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client cursor

Windsurf

npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client windsurf

Manual configuration

Codex

codex mcp add tinyfish --url https://agent.tinyfish.ai/mcp

Grok

grok mcp add --transport http tinyfish https://agent.tinyfish.ai/mcp

Or add to ~/.grok/config.toml (user-level) or .grok/config.toml (project-level):

[mcp_servers.tinyfish]
url = "https://agent.tinyfish.ai/mcp"

Claude Code

claude mcp add --transport http tinyfish https://agent.tinyfish.ai/mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "tinyfish": {
      "url": "https://agent.tinyfish.ai/mcp"
    }
  }
}

Restart Claude Desktop. You’ll be prompted to authenticate via OAuth.

ChatGPT

Add a custom MCP connector in ChatGPT with:

https://agent.tinyfish.ai/mcp/chatgpt

ChatGPT will prompt you to authenticate via OAuth.

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "tinyfish": {
      "url": "https://agent.tinyfish.ai/mcp"
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json (macOS/Linux) or %USERPROFILE%\.codeium\windsurf\mcp_config.json (Windows):

{
  "mcpServers": {
    "tinyfish": {
      "serverUrl": "https://agent.tinyfish.ai/mcp"
    }
  }
}

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_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 narrow or bias results with location (country code, e.g. "US"), language (language code, e.g. "en"), and include_domains / exclude_domains (comma-separated domain allow/deny lists, combined length capped). Use page (0-indexed, 0-10) to paginate. 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.
• 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. Control the output with format ("markdown" default | "html" | "json"), links and image_links (extract outbound/image URLs), ttl (cache freshness tolerance in seconds), and per_url_timeout_ms (per-URL wall-clock budget). Scope extraction with include_selectors / exclude_selectors (1–20 CSS selectors each). For conditional requests, pass if_none_match / if_modified_since (single URL only) and set include_etag_and_last_modified to get the validators back. 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.
• close_browser_session — Close a browser session by ID to release it early instead of waiting for its inactivity timeout. Idempotent — already-ended sessions return success.

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.

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

{
  "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 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 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 — your Claude/Anthropic account
2. 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.

You need a TinyFish account with an active subscription or credits. Sign up here.

Troubleshooting

Tool not showing up

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)

Authentication failing

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
2. In the same browser, sign in to 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

Server disconnected (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

Automation timing out

Complex automations may take 30-60 seconds. For sites with bot protection, the assistant should use browser_profile: "stealth".

Related

Quick Start

Get started with the REST API

API Reference

Full endpoint documentation