# Use Browsable from your agent

Connect Browsable once, then ask your agent for the data you need. You only need to step in when a
			website asks you to sign in or when you want to add more credits.

Start here

- Add `https://mcp.browsable.app` to your agent.

- When prompted, sign in to Browsable in your browser.

- Ask for the data you want. Browsable handles the rest.

## How it works for a person

There is no API key copy-paste step for MCP. There is no separate agent-only account to manage. You
			connect Browsable once, then use it from your agent like any other tool.

- Add Browsable to your agent with the server URL.

- The first time you use it, your agent opens a browser tab so you can log in or create an account.

- After that, ask for what you want: find and run an existing API. Create replacement APIs from the dashboard.

- If a website needs your login, the agent should stop and give you a link.

- If you need more credits, the agent should show your balance and send you to billing, then continue after you upgrade.

What you should expect

- Sign in once.

- Ask for data in plain language.

- Only step in again for a website login or billing.

## Recommended flow for agents

If you are wiring Browsable into an agent or writing system instructions, use this flow.

- Always start with `list_tasks` for a data request, even when the request contains a URL. Pass concise intent keywords in `query`, such as `youtube channel email`.

- If `pagination.has_more` is true, continue with `pagination.next_cursor` before concluding that no existing task is available.

- Use `get_task` before running anything so you know the inputs, outputs, and credit cost.

- Use `run_task` to execute the task. If it runs in the background, check progress with `get_run`.

- If Browsable returns a hosted login link, stop and ask the person to open it. Do not keep retrying.

- If no existing task matches, direct the person to create an API from the dashboard. The legacy `create_scraper` route is retired (HTTP 410).

- If balance or plan status matters, call `get_billing_overview`.

- Only create machine API keys when the user explicitly wants automation outside the current MCP session.

Good agent behavior

- Find the right task before you run it.

- Do not create a scraper merely because the request includes a URL.

- Ask the person for help only when a website login or payment step is required.

- Stay in the same thread and continue after login or billing is done.

- Do not ask the user to copy, paste, or manage session credentials.

## Install Browsable

Use the same server URL everywhere:
`https://mcp.browsable.app` 

### Codex CLI

```bash
codex mcp add browsable --url https://mcp.browsable.app
codex mcp login browsable --scopes tasks.read,tasks.run,runs.read,task_generations.write,billing.read,keys.manage
```

### Claude Code

```bash
claude mcp add --transport http browsable https://mcp.browsable.app
```

### Cursor

```json
{
  "mcpServers": {
    "browsable": {
      "url": "https://mcp.browsable.app"
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "browsable": {
      "type": "http",
      "url": "https://mcp.browsable.app"
    }
  }
}
```

### ChatGPT developer mode

Add Browsable as a custom remote MCP connector and use the same server URL:
`https://mcp.browsable.app`.

## Good first prompts

These are good examples of how to ask for work in plain language.

- Find the best Browsable task for pulling Reddit post comments, then run it for this URL.

- Create a scraper for this page and show me the result.

- Check my remaining Browsable credits.

- If this site needs a login, stop and give me the link.

- Show me the Instagram tasks that fit this job and pick the best one.

## What Browsable handles for you

- Sign-in and account creation the first time you connect.

- Showing the current account balance.

- Finding, running, and tracking tasks.

- Pausing for a website login and bringing you back when it is done.

- Showing balance and upgrade paths when you need more credits.

## If you are not using MCP

You can still use Browsable directly over HTTP. If you are generating code or giving an LLM the raw
			API, start with the [API reference](/docs/api.md)  and [/docs/llms.txt](/docs/llms.txt) .

For direct REST use, discover tasks with `GET /v1/tasks` and run them with
` POST /v1/tasks/{task_key}/runs`.

---
Source: https://browsable-api-ux-staging.pages.dev/docs/guides/agents