Skip to main content

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.

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

​
Quick Install

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

claude mcp add --transport http tinyfish 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, or interacting with a website.
  • 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.
  • 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.
  • 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.
  • get_search_usage — List past search usage records with filtering by date range and status.

​
Content Extraction

  • fetch_content — Render web pages in a real browser 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.
  • 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.

​
Example Usage

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

"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

ToolRate
run_web_automation1 credit per run step
search1 credit = 2 searches
fetch_content1 credit = 15 fetches
create_browser_session1 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

  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)
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
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
Complex automations may take 30-60 seconds. For sites with bot protection, the assistant should use browser_profile: "stealth".

Quick Start

Get started with the REST API

API Reference

Full endpoint documentation