Skip to main content

MCP Tools

The Maxun MCP Server gives your AI client two kinds of tools:

  • One-shot tools that do the work for you: scrape a page, crawl a site, search the web, or describe the data you want and let an AI agent extract it. No robot needs to exist first.
  • Robot and run tools to list, run and inspect the robots you already have, including ones built in Recorder Mode in the dashboard.

Every tool is available on both Maxun Cloud and self-hosted (OSS) Maxun, with the small differences noted below.

Available Tools​

ToolWhat it does
maxun_scrapeTurn one page into markdown, HTML, text, links, a summary or screenshots, and answer questions about it
maxun_crawlCrawl a website and return the content of every page
maxun_searchSearch the web and return results, optionally scraping each one
maxun_agentDescribe the data you want; Maxun's AI builds an extraction robot and runs it
maxun_list_robotsList the robots in your account
maxun_get_robotGet a robot's details
maxun_run_robotRun a robot and return the data it extracts
maxun_get_robot_runsList a robot's runs
maxun_get_runGet a run's status and output
maxun_cancel_runCancel a queued or running run
maxun_get_run_diffSee what changed since the previous run
maxun_get_robot_summaryRun counts, success rate and data totals for a robot
Recorder Mode

Robots that record your clicks in a browser (Recorder Mode) are built in the dashboard. Once built, you can run them, and read and monitor their results, with the robot and run tools.

Renamed tools

All tools now start with maxun_. If you allow-listed tools by name in your client, update the names: list_robots → maxun_list_robots, get_robot → maxun_get_robot, run_robot → maxun_run_robot, get_robot_runs → maxun_get_robot_runs, get_run_details → maxun_get_run, get_robot_summary → maxun_get_robot_summary.

How to Use​

You talk to your AI client in plain language and it picks the tool. Some examples:

You sayTool used
"Get me the pricing page of linear.app as markdown"maxun_scrape
"What does the Pro plan cost on https://example.com/pricing?"maxun_scrape with smart_queries
"Crawl the docs at docs.example.com, only pages under /api/"maxun_crawl
"Find the 5 most recent articles about web scraping regulation this week"maxun_search
"Get the name, price and rating of the first 20 laptops on bestbuy.com"maxun_agent
"Run my Amazon price scraper"maxun_list_robots → maxun_run_robot
"What changed on the last run of my competitor monitor?"maxun_get_robot_runs → maxun_get_run_diff

Robots are saved for you​

maxun_scrape, maxun_crawl, maxun_search and maxun_agent save the robot they build in your account. You can see it in the dashboard, run it again, schedule it, or turn on monitoring for it.

Scrape, crawl and search robots are named after their target, like MCP Scrape: example.com/pricing [3fa2b1c9]. Calling the tool again with the same arguments reuses that robot instead of creating a new one, so repeated calls build up one run history. Pass robot_name to choose the name yourself.

Plan limits

Saved robots count toward your plan's robot limit, and each run uses credits, just like robots you create in the dashboard or through the API.

Long-running work​

Tools wait for the run to finish and return the data. Crawls and large extractions can take several minutes, which is longer than some clients wait for a tool. For those, pass wait: false: the tool returns a run ID straight away, and your AI client can call maxun_get_run later to fetch the result.

"Start a crawl of docs.example.com in the background, then check on it in a few minutes"

One-shot Tools​

maxun_scrape​

Scrapes a single page. Returns the page content as text blocks your AI client can read directly, plus any links, screenshots and smart-query answers.

ParameterRequiredDescription
urlYesThe page to scrape
formatsNoAny of markdown, html, text, links, summary, screenshot-visible, screenshot-fullpage. Default ["markdown"]
smart_queriesNoQuestions to answer from the page, e.g. "What is the price of the Pro plan?"
robot_nameNoName for the saved robot

On self-hosted Maxun, summary and smart_queries need an LLM configured for the MCP server.

maxun_crawl​

Crawls a website from a start URL and returns every page it finds.

ParameterRequiredDescription
urlYesWhere to start
limitNoMaximum pages (default 50)
max_depthNoHow many links deep to go (default 3)
modeNodomain (default), subdomain (also crawl subdomains) or path (only under the start URL's path)
include_pathsNoOnly crawl paths matching these patterns, e.g. ["/docs/"]
exclude_pathsNoSkip paths matching these patterns, e.g. ["/blog/"]
use_sitemapNoFind pages from sitemap.xml (default true)
follow_linksNoFind pages by following links (default true)
respect_robotsNoObey robots.txt (default true)
formatsNoOutput formats per page. Default ["markdown"]
waitNoWait for the crawl to finish (default true). See Long-running work
robot_nameNoName for the saved robot

Learn more about crawl options in Crawl.

Searches the web.

ParameterRequiredDescription
queryYesThe search query
modeNodiscover (default) returns titles, URLs and snippets. scrape also scrapes each result page
limitNoMaximum results (default 10)
time_rangeNoday, week, month or year
formatsNoIn scrape mode, output formats per result. Default ["markdown"]
robot_nameNoName for the saved robot

maxun_agent​

Describe the data you want and Maxun's AI builds an extraction robot for it, the same as AI Mode in the dashboard. It then runs it and returns structured rows. Leave out url and the agent finds the right website itself.

ParameterRequiredDescription
promptYesWhat to extract, at least 15 characters. E.g. "Get the name, price and rating of the first 20 laptops"
urlNoWhere to start. Leave it out to let the agent find the site
robot_nameNoName for the saved robot
runNoRun the robot once built (default true). Set false to only build it
deep_extractionNoCloud only. Follow each item to its detail page for more fields (Deep Extraction, paid plans)
waitNoCloud only. When running, wait for the run to finish (default true)

Building takes a minute or two. The robot is saved, so next time ask your AI client to run it with maxun_run_robot instead of building it again.

On self-hosted Maxun, maxun_agent uses the LLM you configure for the MCP server.


Robot and Run Tools​

maxun_list_robots​

Lists the robots in your account (on Cloud, the team's robots when you connect with a team) with their ID and name. Your AI client uses this to turn a robot's name into its ID, so you can refer to robots by name.

maxun_get_robot​

ParameterRequiredDescription
robot_idYesThe robot ID

maxun_run_robot​

Runs a robot or agent and returns its data. Waits up to 30 minutes on Cloud.

ParameterRequiredDescription
robot_idYesThe robot ID
formatsNoOverride the output formats of a scrape, crawl or search robot
paramsNoCloud only. Input parameters for the robot's workflow
waitNoWait for the run to finish (default true)

maxun_get_robot_runs​

Lists a robot's runs with their ID, status and timestamps.

ParameterRequiredDescription
robot_idYesThe robot ID
limitNoCloud only. Maximum runs (default 20, max 100)

maxun_get_run​

Gets a run's status, and once it has finished, all of its data.

ParameterRequiredDescription
run_idYesThe run ID
robot_idSelf-hosted onlyThe robot the run belongs to

maxun_cancel_run​

Cancels a queued or running run.

ParameterRequiredDescription
run_idYesThe run ID
robot_idSelf-hosted onlyThe robot the run belongs to

maxun_get_run_diff​

For robots with monitoring, shows what changed between a run and the previous successful run.

ParameterRequiredDescription
run_idYesThe run ID
robot_idSelf-hosted onlyThe robot the run belongs to
formatNoOnly show changes for one format, e.g. markdown or captured-list

maxun_get_robot_summary​

Total, successful and failed runs, success rate, and how much data the robot has extracted.

ParameterRequiredDescription
robot_idYesThe robot ID

Common Workflows​

Research a topic​

"Search for the latest news about EU AI Act enforcement this month, scrape the top 5 results and summarize them"

maxun_search (scrape mode) → your AI client summarizes the pages.

Build a reusable extractor​

  1. "Get all job titles, locations and salaries from https://example.com/careers" — maxun_agent builds and runs a robot
  2. "Run the careers robot again" — maxun_run_robot reuses it
  3. Schedule it or turn on monitoring in the dashboard

Watch a page for changes​

  1. "Scrape https://example.com/pricing" — maxun_scrape saves a robot
  2. Turn on monitoring for it in the dashboard, or scrape it again later
  3. "What changed on the pricing page since last time?" — maxun_get_robot_runs → maxun_get_run_diff

Debug a failed run​

  1. "Show me the runs for robot [name]" — find the failed run
  2. "Get the details of run [run-id]" — see the error
  3. "Run robot [name] again" — retry

Tips for Better Prompts​

  • Give the URL when you know it. maxun_scrape is the fastest way to read one page.
  • Be specific with maxun_agent. Name the fields you want and how many items, e.g. "name, price, rating and URL of the first 50 products".
  • Skip robot IDs. Refer to robots by name; your AI client will look them up.
  • Use background runs for big crawls, then ask your client to check on them.

Error Handling​

Errors from Maxun are returned to your AI client with the reason, so it can explain them or fix its request.

ErrorCause
Robot not foundThe robot ID doesn't exist or belongs to another account or team
API key is invalidCheck your key in the Maxun Dashboard
Permission deniedYour team role can view robots but not run them
Robot limit reached / Insufficient creditsYour plan's limits were reached
A robot named "…" already existsPick a different robot_name
The agent could not be builtThe agent couldn't work out how to extract that data; rephrase the prompt or give a url
maxun_agent needs an LLMSelf-hosted: configure an LLM for the MCP server
Run failedThe robot hit an error during extraction; check the run details
Execution timeoutThe run didn't finish within 30 minutes; use wait: false and poll with maxun_get_run