Skip to main content
Set up TinyFish Web Agent in minutes using your AI coding assistant. Just copy the prompt below, drop it into Claude, Cursor, or ChatGPT, and start building your web agent.

​
Three Ways to Get Started

Automation MCP

Let your AI assistant run web automations directly

Docs MCP

Give your AI assistant searchable access to TinyFish docs

Integration Prompt

Paste into any AI assistant to generate custom integration code

​
Automation MCP Server

Connect TinyFish as a tool in your AI assistant so it can browse websites, extract data, and complete multi-step automations on your behalf.

​
Quick Install

npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code
Restart Claude Code for the MCP to load.
claude mcp add --transport http tinyfish https://agent.tinyfish.ai/mcp
For full details on available tools, authentication, and troubleshooting, see the MCP Integration guide.

​
Docs MCP Server

Give your AI assistant searchable access to TinyFish documentation so it can look up API references, code examples, and guides while helping you build integrations.

​
Quick Install

npx -y install-mcp@latest https://docs.tinyfish.ai/mcp --client claude-code
Restart Claude Code for the MCP to load.
claude mcp add --transport http tinyfish-docs https://docs.tinyfish.ai/mcp

​
Integration Prompt

Use this prompt to have your AI assistant generate TinyFish Web Agent integration code tailored to your project.
Copy the entire code block and paste it into Claude, ChatGPT, Cursor, or any AI coding assistant.
I need help integrating TinyFish Web Agent into my project. TinyFish Web Agent is a web automation API that uses natural language to control browsers - no CSS selectors or XPath needed.

**TinyFish Web Agent capabilities:**
- Navigate to websites and perform actions (clicks, form fills, scrolling)
- Extract structured data from any page as JSON
- Handle multi-step workflows with a single API call
- Work on authenticated and bot-protected sites

Please ask me these questions first:

1. What am I building?
   - Data extraction / scraping
   - Form automation
   - Web monitoring
   - AI agent with web browsing
   - Something else

2. Which endpoint should I use?
   - Synchronous (/run) - wait for result, simple code
   - Async (/run-async) - start task, poll for result later
   - Streaming (/run-sse) - real-time progress updates

3. What's my tech stack?
   - TypeScript / JavaScript
   - Python
   - Other

4. Will I need anti-detection?
   - No - standard websites
   - Yes - sites with Cloudflare, CAPTCHAs, or bot protection

Then generate code using these patterns:

---

**Environment Setup**

```bash
# Get your API key at https://agent.tinyfish.ai/api-keys
# Add to .env file:
TINYFISH_API_KEY=sk-tinyfish-*****
```

---

**TypeScript - Streaming (Recommended)**

```typescript
import { TinyFish, EventType, RunStatus } from "@tiny-fish/sdk";

const client = new TinyFish();  // Reads TINYFISH_API_KEY from environment

async function runAutomation(url: string, goal: string) {
  const stream = await client.agent.stream({ url, goal });

  for await (const event of stream) {
    if (event.type === EventType.PROGRESS) {
      console.log(`Action: ${event.purpose}`);
    } else if (event.type === EventType.COMPLETE) {
      if (event.status === RunStatus.COMPLETED) {
        return event.result;
      }
      throw new Error(event.error?.message || "Automation failed");
    }
  }
}

// Example usage
const products = await runAutomation(
  "https://example.com/products",
  "Extract all product names and prices as JSON"
);
```

---

**TypeScript - Synchronous**

```typescript
import { TinyFish, RunStatus } from "@tiny-fish/sdk";

const client = new TinyFish();  // Reads TINYFISH_API_KEY from environment

async function runAutomation(url: string, goal: string) {
  const run = await client.agent.run({ url, goal });
  if (run.status === RunStatus.COMPLETED) return run.result;
  throw new Error(run.error?.message || "Automation failed");
}
```

---

**Python - Streaming**

```python
from tinyfish import TinyFish, EventType, RunStatus

client = TinyFish()  # Reads TINYFISH_API_KEY from environment

def run_automation(url: str, goal: str):
    with client.agent.stream(url=url, goal=goal) as stream:
        for event in stream:
            if event.type == EventType.PROGRESS:
                print(f"Action: {event.purpose}")
            elif event.type == EventType.COMPLETE:
                if event.status == RunStatus.COMPLETED:
                    return event.result_json
                raise Exception(event.error)

# Example usage
products = run_automation(
    "https://example.com/products",
    "Extract all product names and prices as JSON"
)
```

---

**Python - Synchronous**

```python
from tinyfish import TinyFish, RunStatus

client = TinyFish()  # Reads TINYFISH_API_KEY from environment

def run_automation(url: str, goal: str):
    result = client.agent.run(url=url, goal=goal)
    if result.status == RunStatus.COMPLETED:
        return result.result
    raise Exception(result.error)
```

---

**Anti-Detection Mode**

For sites with bot protection, add stealth mode and proxy:

```typescript
import { BrowserProfile, ProxyCountryCode } from "@tiny-fish/sdk";

const run = await client.agent.run({
  url: "https://protected-site.com",
  goal: "Extract pricing data",
  browser_profile: BrowserProfile.STEALTH,
  proxy_config: {
    enabled: true,
    country_code: ProxyCountryCode.US,  // Also: GB, CA, DE, FR, JP, AU
  },
});
```

---

**Writing Good Goals**

Be specific about what you want:

```
// Good - specific output format
"Extract product name, price, and availability. Return as JSON array."

// Good - multi-step with numbered actions
"1. Click 'Load More' 3 times  2. Extract all product cards  3. Return as JSON"

// Bad - too vague
"Get the data"
```

---

**Quick Test**

```bash
curl -N -X POST https://agent.tinyfish.ai/v1/automation/run-sse \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://scrapeme.live/shop",
    "goal": "Extract the first 3 product names and prices"
  }'
```

---

After asking the questions, generate the appropriate code for my use case. Reference https://docs.tinyfish.ai for additional details.

​
Next Steps

Quick Start

Manual step-by-step setup

Prompting Guide

Write goals that work on the first try

AI Integration Guide

Advanced patterns for AI agents

API Reference

Full endpoint documentation