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 mcpor through Python with uv:
uvx node-mantis mcpBoth 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.
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:
- Copy an API key from the dashboard.
- Add the entry below to your assistant. Where it goes depends on the assistant; see the table and the sections that follow.
- 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-mantisis the name the assistant shows for the server. You can change it.commandandargsare how the assistant starts the server. Use either the Node.js or the Python version; both give the assistant the same tools.envholds settings the assistant passes to the server when it starts it. Replace the placeholder with your API key. If you already saved a key withnodemantis configure, you can leaveenvout.
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.
| Assistant | Where the entry goes |
|---|---|
| Claude Code | One command in your terminal. |
| Claude Desktop | claude_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. |
| Codex | One command in your terminal, or ~/.codex/config.toml. |
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 mcpWith Python:
claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcpclaude mcp list then shows node-mantis as connected.
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.
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 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"].
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 mcpWith Python:
codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcpOr 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"].
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>" }
}
}
}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.
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>" }
}
}
}| Tool | Description |
|---|---|
run_task | Carry out a task on a website from a plain-English goal: navigate, click, type, fill in forms and read the outcome. |
retrieve_data | Open one page and read data from it without changing anything on it. |
get_task | Wait for a task and return its status, latest progress and result. |
cancel_task | Stop 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.
Works like run in the SDK. Only goal is required.
| Parameter | Type | Default | Description |
|---|---|---|---|
goal | string | required | What to accomplish, in plain English, with every detail needed to finish it. |
start_url | string | none | Page to open first. Without it the task finds its own way from the goal. |
result_schema | object | free-form | JSON Schema for the data to return. The result then carries the data in that shape. |
effort | low | medium | high | xhigh | medium | How much capability to spend. Higher effort can handle harder pages and costs more. |
max_cost_usd | number | no ceiling | USD budget checked between steps. The final step can take total spend above this amount. |
max_steps | integer | 30 | Maximum number of steps before the task stops. |
timeout_seconds | integer | 300 | Overall time limit for the task. |
secrets | string[] | none | Names of private values the task can type. Each value is read from NODEMANTIS_SECRET_<NAME> in the server's environment. |
use_proxy | boolean | false | Routes the browser through the proxy configured in the server's environment. |
show_browser | boolean | false | Shows the browser window while the task runs. |
Works like retrieve in the SDK. Use run_task instead when reaching the data takes clicking, typing or several pages.
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | required | The page to read. |
prompt | string | required | What to read from the page. |
result_schema | object | free-form | JSON Schema for the shape of the returned data. |
effort | low | medium | high | xhigh | medium | How much capability to spend on reading the page. |
use_proxy | boolean | false | Routes the browser through the proxy configured in the server's environment. |
show_browser | boolean | false | Shows the browser window while the page is read. |
| Parameter | Type | Default | Description |
|---|---|---|---|
task_id | string | required | The task_id returned by run_task or retrieve_data. |
wait_seconds | integer | 45 | How long to wait for the task to finish before answering. 0 answers immediately. |
Takes a task_id. A task that already finished is left unchanged.
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.
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.
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.
Add these after mcp in the args list.
| Parameter | Type | Default | Description |
|---|---|---|---|
--wait-seconds <n> | number | 45 | How 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> | number | 4 | How many tasks can run at the same time. |
-H, --headed | flag | headless | Shows the browser window for every task unless a tool call sets show_browser. |
- The assistant reports that no API key is configured. Add
NODEMANTIS_API_KEYto the server'senv, or runnodemantis configureonce, then try again. No restart is needed afterconfigure. - The server times out on its first start. The first
npxlaunch downloads the package. Install it once withnpm install -g node-mantisand start the installed command instead:{ "mcpServers": { "node-mantis": { "command": "nodemantis", "args": ["mcp"] } } } - Tasks fail to start. Run
nodemantis doctorto check the installation, browser and API key.
