MCP server

Node Mantis includes a Model Context Protocol (MCP) server. Add it to an AI assistant that supports MCP, such as Claude Code, Claude Desktop, Cursor, VS Code or Codex, and the assistant can carry out tasks on websites for you: it describes the task, Node Mantis works through the site in a real browser and returns the result as structured data.

Adding the server to your coding agent or assistant lets you:

  • Carry out website tasks. Give a goal in plain English and Node Mantis works through the site like a real user would: clicking, typing, and handling forms, dropdowns and date pickers.
  • Get structured results. Provide a JSON Schema and Node Mantis returns the result as data that matches it.
  • Run long tasks in the background. A task that takes minutes keeps running while your assistant checks on it, reports progress, or cancels it.

The server is part of the node-mantis package on npm and on PyPI, so there is nothing separate to install. Your assistant starts it with one command, through Node.js:

npx -y node-mantis mcp

or through Python with uv:

uvx node-mantis mcp

Both give the assistant the same tools. You need Node.js or Python, Google Chrome and an API key from the dashboard. If Chrome is not installed, the first task downloads Chrome for Testing.

Add it to your assistant

Every assistant keeps a list of MCP servers in its settings. You add one entry for Node Mantis, either with a command or by editing the assistant's settings file, and the assistant starts the server itself whenever it needs it. There are three steps:

  1. Copy an API key from the dashboard.
  2. Add the entry below to your assistant. Where it goes depends on the assistant; see the table and the sections that follow.
  3. Restart the assistant and check that it works.

Most assistants read the same JSON entry. With Node.js:

{
  "mcpServers": {
    "node-mantis": {
      "command": "npx",
      "args": ["-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

With Python:

{
  "mcpServers": {
    "node-mantis": {
      "command": "uvx",
      "args": ["node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

The entry has three parts:

  • node-mantis is the name the assistant shows for the server. You can change it.
  • command and args are how the assistant starts the server. Use either the Node.js or the Python version; both give the assistant the same tools.
  • env holds settings the assistant passes to the server when it starts it. Replace the placeholder with your API key. If you already saved a key with nodemantis configure, you can leave env out.

If the settings file already has an mcpServers section, add the node-mantis entry inside it next to the others instead of pasting a second mcpServers.

AssistantWhere the entry goes
Claude CodeOne command in your terminal.
Claude Desktopclaude_desktop_config.json, opened from Settings.
Cursor~/.cursor/mcp.json for every project, or .cursor/mcp.json in one project.
VS Code.vscode/mcp.json in your workspace.
CodexOne command in your terminal, or ~/.codex/config.toml.

Claude Code

Run one of these in your terminal. With Node.js:

claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp

With Python:

claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp

claude mcp list then shows node-mantis as connected.

Claude Desktop

Open Settings, then Developer, then Edit Config. This opens claude_desktop_config.json, which is stored in ~/Library/Application Support/Claude/ on macOS and in %APPDATA%\Claude\ on Windows. Add the JSON entry above, save the file and restart the app.

Cursor

Add the JSON entry above to ~/.cursor/mcp.json to use it in every project, or to .cursor/mcp.json inside one project. Create the file if it does not exist.

VS Code

VS Code uses servers instead of mcpServers. Add this to .vscode/mcp.json in your workspace:

{
  "servers": {
    "node-mantis": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

For Python, set command to uvx and args to ["node-mantis", "mcp"].

Codex

Run one of these in your terminal. With Node.js:

codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp

With Python:

codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp

Or edit ~/.codex/config.toml. The longer start-up limit gives the first launch time to download the package:

[mcp_servers.node-mantis]
command = "npx"
args = ["-y", "node-mantis", "mcp"]
startup_timeout_sec = 60

[mcp_servers.node-mantis.env]
NODEMANTIS_API_KEY = "sk_live_<copy-from-dashboard>"

For Python, set command to "uvx" and args to ["node-mantis", "mcp"].

Python without uv

The Python examples above use uv, which fetches the package from PyPI on first use. Without uv, install the package once with python -m pip install node-mantis and use nodemantis as the command with mcp as its only argument:

{
  "mcpServers": {
    "node-mantis": {
      "command": "nodemantis",
      "args": ["mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Check that it works

After a restart, the assistant lists node-mantis among its MCP servers with four tools. Then ask it for a task, for example:

Use Node Mantis to open https://sandbox.nodemantis.com and tell me the title and price of the first book.

The assistant calls run_task and answers with what the task found. If it does not, see Troubleshooting.

Windows

If the assistant cannot start npx directly, run it through cmd:

{
  "mcpServers": {
    "node-mantis": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Tools

ToolDescription
run_taskCarry out a task on a website from a plain-English goal: navigate, click, type, fill in forms and read the outcome.
retrieve_dataOpen one page and read data from it without changing anything on it.
get_taskWait for a task and return its status, latest progress and result.
cancel_taskStop a running task and close its browser.

Each task runs in its own fresh browser session, with no saved logins, and the session closes when the task ends.

run_task

Works like run in the SDK. Only goal is required.

ParameterTypeDefaultDescription
goalstringrequiredWhat to accomplish, in plain English, with every detail needed to finish it.
start_urlstringnonePage to open first. Without it the task finds its own way from the goal.
result_schemaobjectfree-formJSON Schema for the data to return. The result then carries the data in that shape.
effortlow | medium | high | xhighmediumHow much capability to spend. Higher effort can handle harder pages and costs more.
max_cost_usdnumberno ceilingUSD budget checked between steps. The final step can take total spend above this amount.
max_stepsinteger30Maximum number of steps before the task stops.
timeout_secondsinteger300Overall time limit for the task.
secretsstring[]noneNames of private values the task can type. Each value is read from NODEMANTIS_SECRET_<NAME> in the server's environment.
use_proxybooleanfalseRoutes the browser through the proxy configured in the server's environment.
show_browserbooleanfalseShows the browser window while the task runs.

retrieve_data

Works like retrieve in the SDK. Use run_task instead when reaching the data takes clicking, typing or several pages.

ParameterTypeDefaultDescription
urlstringrequiredThe page to read.
promptstringrequiredWhat to read from the page.
result_schemaobjectfree-formJSON Schema for the shape of the returned data.
effortlow | medium | high | xhighmediumHow much capability to spend on reading the page.
use_proxybooleanfalseRoutes the browser through the proxy configured in the server's environment.
show_browserbooleanfalseShows the browser window while the page is read.

get_task

ParameterTypeDefaultDescription
task_idstringrequiredThe task_id returned by run_task or retrieve_data.
wait_secondsinteger45How long to wait for the task to finish before answering. 0 answers immediately.

cancel_task

Takes a task_id. A task that already finished is left unchanged.

Long tasks

A website task can take longer than an assistant is willing to wait for one tool call. run_task and retrieve_data therefore wait up to 45 seconds. If the task finishes in that time, the call returns the result. Otherwise it returns status running with a task_id, and the task keeps going in the background:

{
  "task_id": "task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10",
  "tool": "run_task",
  "status": "running",
  "elapsed_seconds": 45,
  "progress": {
    "step": 6,
    "max_steps": 30,
    "message": "Step 6/30: The cart shows one book. — click(\"Checkout\")"
  },
  "next_step": "Still running. Call get_task with task_id \"task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10\" to wait for the result, or cancel_task to stop it."
}

The assistant then calls get_task with that id until the status is succeeded, failed or cancelled:

{
  "task_id": "task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10",
  "tool": "run_task",
  "status": "succeeded",
  "elapsed_seconds": 71,
  "result": {
    "ok": true,
    "reason": "Added the book to the cart and read the cart.",
    "value": { "title": "Journey to the Center of the Earth", "quantity": 1 },
    "steps": 9,
    "cost_usd": 0.04,
    "trace_id": "op_1794979105280_5c3e8996"
  }
}

A failed task still returns what it found, with the reason, so the assistant can adjust the goal and try again. Finished tasks are kept for an hour. Tasks belong to the running server: they stop when your assistant closes the server.

Secrets

Passwords and one-time codes never pass through the conversation. Set each value in the server's environment as NODEMANTIS_SECRET_<NAME>, next to the API key in env. The assistant passes only the names in secrets and refers to a value in the goal as <secret:NAME>. See Secrets.

Proxy

To send a task's browser through a proxy, set NODEMANTIS_PROXYin the server's environment and have the task pass use_proxy. Proxy lists and files work as described in Proxy configuration.

Server options

Add these after mcp in the args list.

ParameterTypeDefaultDescription
--wait-seconds <n>number45How long a tool call waits for a task before it returns the task id. Lower it if your assistant gives up on tool calls sooner.
--max-tasks <n>number4How many tasks can run at the same time.
-H, --headedflagheadlessShows the browser window for every task unless a tool call sets show_browser.

Troubleshooting

  • The assistant reports that no API key is configured. Add NODEMANTIS_API_KEY to the server's env, or run nodemantis configure once, then try again. No restart is needed after configure.
  • The server times out on its first start. The first npx launch downloads the package. Install it once with npm install -g node-mantis and start the installed command instead:
    {
      "mcpServers": {
        "node-mantis": {
          "command": "nodemantis",
          "args": ["mcp"]
        }
      }
    }
  • Tasks fail to start. Run nodemantis doctor to check the installation, browser and API key.