> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal): > ```bash > npx -y @scalekit-inc/cli setup -y > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup -y > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Connect AI agents to the Tinyfish MCP server The Tinyfish MCP connector routes your AI agent's tool calls to Tinyfish's own MCP server through Scalekit. Each user signs in to Tinyfish once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 19 tools. **Authentication:** OAuth 2.1/DCR **Categories:** Automation, AI, Developer Tools **Tools:** 19: 12 read, 2 write, 5 destructive **Users sign in with:** OAuth **OAuth app:** Scalekit's or your own **Built by:** Vendor MCP **Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=TINYFISHMCP) ## What you can do - **Automate websites**: run multi-step tasks on a site from a plain-language goal, including clicks, form fills, and navigation - **Fetch page content**: render up to 10 URLs in a real browser and return clean markdown, HTML, or JSON - **Search the web**: get structured results with titles, snippets, and URLs, targeted by location and language - **Track automation runs**: check status, view step-by-step traces with screenshots, and cancel runs - **Run browser sessions**: start remote Chrome sessions to drive with Playwright, Puppeteer, or Selenium, and close them ## Setup 1. ### Install the SDK **Node.js** ```bash npm install @scalekit-sdk/node dotenv ``` **Python** ```bash pip install scalekit-sdk-python python-dotenv ``` 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` 3. ### Create the Tinyfish MCP connection In **AgentKit > Connections**, create a Tinyfish MCP connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/). Scalekit credentials are available for Tinyfish MCP server, so you don't need to register an OAuth app. 4. ### Authorize a user and make your first call **Node.js** (`quickstart.mts`) ```typescript import { ScalekitClient } from '@scalekit-sdk/node' import 'dotenv/config' import { createInterface } from 'node:readline/promises' const scalekit = new ScalekitClient( process.env.SCALEKIT_ENVIRONMENT_URL, process.env.SCALEKIT_CLIENT_ID, process.env.SCALEKIT_CLIENT_SECRET, ) const actions = scalekit.actions const connector = 'tinyfishmcp' const identifier = 'user_123' // Generate an authorization link for the user const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier }) console.log('Authorize Tinyfish MCP:', link) const rl = createInterface({ input: process.stdin, output: process.stdout }) await rl.question('Press Enter after authorizing...') rl.close() // Make your first call const result = await actions.executeTool({ connector, identifier, toolName: 'tinyfishmcp_get_wallet', toolInput: {}, }) console.log(result) ``` ```bash npx tsx quickstart.mts ``` **Python** (`quickstart.py`) ```python import os from scalekit import ScalekitClient from dotenv import load_dotenv load_dotenv() scalekit_client = ScalekitClient( env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), ) actions = scalekit_client.actions connection_name = "tinyfishmcp" identifier = "user_123" # Generate an authorization link for the user link_response = actions.get_authorization_link( connection_name=connection_name, identifier=identifier, ) print("Authorize Tinyfish MCP:", link_response.link) input("Press Enter after authorizing...") # Make your first call result = actions.execute_tool( tool_input={}, tool_name="tinyfishmcp_get_wallet", connection_name=connection_name, identifier=identifier, ) print(result) ``` ```bash python quickstart.py ``` Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses. ## Tools Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool). **Node.js** ```typescript const result = await actions.executeTool({ toolName: 'tinyfishmcp_batch_status', toolInput: { run_ids: [], }, connector: 'tinyfishmcp', identifier: 'user_123', }) ``` **Python** ```python result = actions.execute_tool( tool_name="tinyfishmcp_batch_status", tool_input={ "run_ids": [], }, connection_name="tinyfishmcp", identifier="user_123", ) ``` `result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call. ### `tinyfishmcp_batch_status` Batch Status · Read-only Check the status, result, and error for up to 8 automation runs by their IDs. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `run_ids` (`array`, required): List of run IDs to cancel or check status for (up to 8). Example input: `{"run_ids":[]}` ### `tinyfishmcp_discover_run` Discover Run · Read-only Return the run ID of the currently active automation for the given session, or null if no run is in progress. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `session_id` (`string`, required): The browser session ID to look up the running automation for. Example input: `{"session_id":""}` ### `tinyfishmcp_fetch_content` Fetch Content · Read-only Render up to 10 URLs in a real browser and return clean structured content (markdown, HTML, or JSON) plus metadata like title, author, and publish date. Fetches run in parallel; per-URL errors are reported without blocking the rest. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `format` (`string`, required): Output format for extracted content. Accepted values: markdown, html, json. One of: `markdown`, `html`, `json`. Default: `markdown`. - `image_links` (`boolean`, required): Set to true to extract all image URLs from each page. Default: `false`. - `links` (`boolean`, required): Set to true to extract all hyperlinks from each page. Default: `false`. - `page_metadata` (`boolean`, required): Return page-head metadata for each page in the page_metadata object of each result: canonical URL, favicon, robots directive, generator, viewport, keywords, all Open Graph (og), Twitter card (twitter), and article tags, and remaining named meta tags under other. Useful for SEO/technical audits and link-preview generation. Default: `false`. - `urls` (`array`, required): List of URLs to fetch content from. - `exclude_selectors` (`array`, optional): Array of CSS selectors (1-20 entries, each 1-1000 characters) for elements to remove before extraction — applied before include_selectors scopes what remains, so it also prunes inside selected regions. Entries that match nothing are a no-op, never an error, but URLs that resolve to direct PDF/CSV downloads fail with selector_unsupported. Invalid CSS selector syntax is rejected with a 422. - `if_modified_since` (`string`, optional): Last-Modified validator from a prior fetch of this URL, forwarded verbatim as the If-Modified-Since header on the origin request. Only valid with a single URL — combining with a batch of URLs returns a 400. tf-fetch does not persist validators; the caller owns replaying them. - `if_none_match` (`string`, optional): ETag validator from a prior fetch of this URL, forwarded verbatim as the If-None-Match header on the origin request. Only valid with a single URL — combining with a batch of URLs returns a 400. tf-fetch does not persist validators; the caller owns replaying them. - `include_etag_and_last_modified` (`boolean`, optional): Opt-in to receiving etag / last_modified validators (and not_modified detection) on each result. Defaults to false — tf-fetch omits these fields unless requested. Independent of if_none_match / if_modified_since: works with a single URL or a batch. - `include_selectors` (`array`, optional): Array of CSS selectors (1-20 entries, each 1-1000 characters) that scope extracted content (text, links, image_links) to elements matching ANY entry, concatenated in document order. Selected content is returned verbatim in the requested format (scripts/styles stripped) — automatic boilerplate removal is bypassed. When no entry matches anything, that URL fails with the per-URL error code selector_not_matched. URLs that resolve to direct PDF/CSV downloads fail with selector_unsupported. Invalid CSS selector syntax is rejected with a 422. - `per_url_timeout_ms` (`integer`, optional): Wall-clock timeout budget in milliseconds applied independently to each URL. If one URL exceeds this budget, it returns a per-URL timeout error while other URLs in the same request continue. - `purpose` (`string`, optional): Why these URLs are being fetched — the underlying goal or task the content will be used for. Used to better tailor fetching and extraction to your intent. - `ttl` (`integer`, optional): Cache TTL in seconds for fetched content. Omit to disable caching. Example input: `{"format":"markdown","image_links":false,"links":false,"page_metadata":false,"urls":[]}` ### `tinyfishmcp_get_run` Get Run · Read-only Retrieve status, result, error, and metadata for a specific automation run by its ID. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `id` (`string`, required): The unique run ID to retrieve or cancel. Example input: `{"id":""}` ### `tinyfishmcp_get_search_usage` Get Search Usage · Read-only List past search usage records with optional filtering by date range and status, for auditing query history and credit consumption. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `limit` (`integer`, required): Maximum number of results to return per page. Default: `100`. - `page` (`integer`, required): Page number for paginated results. Default: `1`. - `end_before` (`string`, optional): Return records ending before this ISO 8601 timestamp. - `start_after` (`string`, optional): Return records starting after this ISO 8601 timestamp. - `status` (`string`, optional): Filter by run or session status (e.g. completed, failed, running). One of: `completed`, `failed`. Example input: `{"limit":100,"page":1}` ### `tinyfishmcp_get_steps` Get Steps · Read-only Retrieve the step-by-step execution trace for an automation run, including screenshots captured at each step. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `runId` (`string`, required): The unique run ID to retrieve steps or poll status for. Example input: `{"runId":""}` ### `tinyfishmcp_get_wallet` Get Wallet · Read-only Read-only. Returns the caller's current wallet balance, auto-reload state, per-product contract rates, and any in-flight top-up. Wallet top-ups and auto-reload changes happen in the dashboard, not through this tool. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `tinyfishmcp_guide_next_step` Onboarding: Next Step · Read-only Returns the next interactive TinyFish onboarding step based on the user's real usage. Ask for the user's input and wait before running the suggested tool. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: none. Example input: `{}` ### `tinyfishmcp_list_browser_sessions` List Browser Sessions · Read-only List browser sessions with optional filtering by session ID, time range, and status, returning duration, data usage, and connection metadata. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `limit` (`integer`, required): Maximum number of results to return per page. Default: `100`. - `page` (`integer`, required): Page number for paginated results. Default: `1`. - `end_before` (`string`, optional): Return records ending before this ISO 8601 timestamp. - `session_id` (`string`, optional): The browser session ID for an active cloud session. - `start_after` (`string`, optional): Return records starting after this ISO 8601 timestamp. - `status` (`string`, optional): Filter by run or session status (e.g. completed, failed, running). One of: `running`, `ended`. Example input: `{"limit":100,"page":1}` ### `tinyfishmcp_list_fetch_usage` List Fetch Usage · Read-only List past fetch content requests with optional filtering by date range and status. Does not include the fetched text content. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `limit` (`integer`, required): Maximum number of results to return per page. Default: `20`. - `page` (`integer`, required): Page number for paginated results. Default: `1`. - `end_before` (`string`, optional): Return records ending before this ISO 8601 timestamp. - `start_after` (`string`, optional): Return records starting after this ISO 8601 timestamp. - `status` (`string`, optional): Filter by run or session status (e.g. completed, failed, running). One of: `completed`, `failed`. Example input: `{"limit":20,"page":1}` ### `tinyfishmcp_list_runs` List Runs · Read-only List automation runs with optional filtering by status, goal text, and date range, with cursor-based pagination. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `limit` (`integer`, required): Maximum number of results to return per page. Default: `20`. - `sort_direction` (`string`, required): Sort direction. Accepted values: asc, desc. One of: `asc`, `desc`. Default: `desc`. - `created_after` (`string`, optional): Return runs created after this ISO 8601 timestamp. - `created_before` (`string`, optional): Return runs created before this ISO 8601 timestamp. - `cursor` (`string`, optional): Pagination cursor from the previous response to fetch the next page. - `goal` (`string`, optional): Natural language description of what to accomplish on the website. - `status` (`string`, optional): Filter by run or session status (e.g. completed, failed, running). One of: `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`. Example input: `{"limit":20,"sort_direction":"desc"}` ### `tinyfishmcp_poll_status` Poll Status · Read-only Return the current status, step count, and progress for an automation run. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `runId` (`string`, required): The unique run ID to retrieve steps or poll status for. Example input: `{"runId":""}` ### `tinyfishmcp_create_browser_session` Create Browser Session · Write Create a remote stealth Chrome browser session in the cloud and return CDP connection details (session_id, cdp_url) for use with Playwright, Puppeteer, or Selenium. Sessions auto-terminate after the configured inactivity timeout. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `timeout_seconds` (`integer`, optional): Browser session timeout in seconds. - `url` (`string`, optional): Target website URL to automate. Example input: `{}` ### `tinyfishmcp_search` Search · Write Search the web and return structured results with titles, snippets, and URLs. Supports geo-targeting and language filtering. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `query` (`string`, required): Search query to run. - `after_date` (`string`, optional): Return results after this date (YYYY-MM-DD). Do not combine with recency_minutes. - `before_date` (`string`, optional): Return results before this date (YYYY-MM-DD). Do not combine with recency_minutes. - `domain_type` (`string`, optional): Type of search to perform: "web" for standard results, "news" for news articles, "research_paper" for academic papers. Defaults to "web". One of: `web`, `news`, `research_paper`. - `exclude_domains` (`string`, optional): Comma-separated list of domains to exclude from results. - `fetch` (`string`, optional): Fetch mode for search results. Accepted values: none, snippet, full. - `include_domains` (`string`, optional): Comma-separated list of domains to restrict results to. - `include_thumbnail` (`string`, optional): Set to true to include thumbnail images in search results. One of: `true`, `false`. - `language` (`string`, optional): Language code to filter search results (e.g. en). - `location` (`string`, optional): Location to filter search results (e.g. United States). - `page` (`integer`, optional): Page number for paginated results. - `pub_year_max` (`integer`, optional): Return research papers published on or before this year (0-9999, inclusive). Only supported for domain_type=research_paper. - `pub_year_min` (`integer`, optional): Return research papers published on or after this year (0-9999, inclusive). Only supported for domain_type=research_paper. - `purpose` (`string`, optional): Why this search is being run — the underlying goal or task the results will be used for. Used to better rank results against your intent. - `recency_minutes` (`integer`, optional): Return results from the past N minutes (1 to 5,256,000). Do not combine with after_date or before_date. Example input: `{"query":""}` ### `tinyfishmcp_batch_cancel` Batch Cancel · Destructive Cancel up to 8 running or pending automation runs by their IDs. Already-terminal runs are returned with their current status. Read only: no. Destructive: yes. Idempotent (safe to retry): no. Inputs: - `run_ids` (`array`, required): List of run IDs to cancel or check status for (up to 8). Example input: `{"run_ids":[]}` ### `tinyfishmcp_cancel_run` Cancel Run · Destructive Cancel a running or pending automation run by its ID. Returns current status without error if the run has already reached a terminal state. Read only: no. Destructive: yes. Idempotent (safe to retry): no. Inputs: - `id` (`string`, required): The unique run ID to retrieve or cancel. Example input: `{"id":""}` ### `tinyfishmcp_close_browser_session` Close Browser Session · Destructive Only use when the user explicitly wants to stop or close a remote browser session. Closes a session by ID. Idempotent — already-ended sessions return success. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `session_id` (`string`, required): ID of the browser session to close Example input: `{"session_id":""}` ### `tinyfishmcp_run_web_automation` Run Web Automation · Destructive Execute multi-step web automation on a URL using a natural language goal — clicks, form fills, and navigation. If the tool times out, the run is still executing on the server; use get_run or list_runs to check status. Read only: no. Destructive: yes. Idempotent (safe to retry): no. Inputs: - `goal` (`string`, required): Natural language description of what to accomplish on the website. - `session_id` (`string`, required): The browser session ID for an active cloud session. - `url` (`string`, required): Target website URL to automate. - `agent_config` (`object`, optional): Agent behavior configuration (max_steps, mode, cursor_style, max_duration_seconds). - `api_integration` (`string`, optional): Name of the integration making this call (e.g. zapier, n8n). Used for analytics. - `browser_profile` (`string`, optional): Browser execution profile. Accepted values: lite, stealth. One of: `lite`, `stealth`. - `capture_config` (`object`, optional): Configure which data to capture during the run (screenshots, recording, html, etc.). - `credential_item_ids` (`array`, optional): Scope vault credentials to specific credential URIs. Requires use_vault to be true. - `feature_flags` (`object`, optional): Feature flags to enable for this run. - `output_schema` (`object`, optional): Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted. - `profile_id` (`string`, optional): Browser profile ID to use when use_profile is true. - `proxy_config` (`object`, optional): Proxy configuration for this run (enabled, type, url, country_code). - `use_profile` (`boolean`, optional): Set to true to use the default browser profile if profiles are enabled. - `use_vault` (`boolean`, optional): Set to true to include enabled vault credentials for this run. - `webhook_url` (`string`, optional): HTTPS URL to receive webhook notifications for run lifecycle events. Example input: `{"goal":"","session_id":"","url":""}` ### `tinyfishmcp_run_web_automation_async` Run Web Automation Async · Destructive Start a single web automation in the background and return the run ID immediately without waiting for completion. Poll with get_run every 30–60 seconds. Read only: no. Destructive: yes. Idempotent (safe to retry): no. Inputs: - `goal` (`string`, required): Natural language description of what to accomplish on the website. - `session_id` (`string`, required): The browser session ID for an active cloud session. - `url` (`string`, required): Target website URL to automate. - `agent_config` (`object`, optional): Agent behavior configuration (max_steps, mode, cursor_style, max_duration_seconds). - `api_integration` (`string`, optional): Name of the integration making this call (e.g. zapier, n8n). Used for analytics. - `browser_profile` (`string`, optional): Browser execution profile. Accepted values: lite, stealth. One of: `lite`, `stealth`. - `capture_config` (`object`, optional): Configure which data to capture during the run (screenshots, recording, html, etc.). - `credential_item_ids` (`array`, optional): Scope vault credentials to specific credential URIs. Requires use_vault to be true. - `feature_flags` (`object`, optional): Feature flags to enable for this run. - `output_schema` (`object`, optional): Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted. - `profile_id` (`string`, optional): Browser profile ID to use when use_profile is true. - `proxy_config` (`object`, optional): Proxy configuration for this run (enabled, type, url, country_code). - `use_profile` (`boolean`, optional): Set to true to use the default browser profile if profiles are enabled. - `use_vault` (`boolean`, optional): Set to true to include enabled vault credentials for this run. - `webhook_url` (`string`, optional): HTTPS URL to receive webhook notifications for run lifecycle events. Example input: `{"goal":"","session_id":"","url":""}` ## Related Other Automation connectors ([all 58](/agentkit/connectors/?category=automation)): - [Mailchimp](/agentkit/connectors/mailchimp/): Scalekit connector, OAuth, 73 tools - [Twilio](/agentkit/connectors/twilio/): Scalekit connector, Username and password, 61 tools - [Stripe](/agentkit/connectors/stripe/): Scalekit connector, Access token, 178 tools --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |