Connect AI agents over MCP

NinjaSurfer speaks MCP (Model Context Protocol), the standard way AI agents use tools. Once your agent is connected, it can manage your profiles and work in their browsers when you ask it in plain words.

What you get

Everything runs on your computer. The agent starts NinjaSurfer's MCP server by itself whenever it needs it, and every call is written to a local log.

Before you start

• The NinjaSurfer app is installed and you are signed in.
• Your plan is active: starting a profile from an agent follows the same rules as starting it in the app.
• You use an MCP client, for example Claude Code, Claude Desktop, Cursor, Windsurf or VS Code.

Add NinjaSurfer to your agent

This is the recommended way. The app writes the right settings for your computer, and you do it once: the agent keeps finding NinjaSurfer after app updates.

1. Open the NinjaSurfer app and go to Agents (MCP).
2. Under Add to your agent, click Add next to your agent and confirm.
3. Restart the agent (or reload its MCP servers) so it picks up the new entry.
4. Ask the agent to use NinjaSurfer, for example: “List my NinjaSurfer profiles.”

One-click setup is available for:

Claude Code Claude Desktop Cursor Windsurf VS Code (Copilot) Cline Codex CLI Gemini CLI Zed Continue

The app changes only the NinjaSurfer entry in the agent's settings; everything else there stays as it is.

Disconnect an agent

In Agents (MCP), select the agent that shows ✓ Added, click Remove from … and confirm with Remove. The app keeps a copy of the agent's settings file next to it. Restart the agent afterwards.

Manual setup for other MCP clients

Any client that can start an MCP server as a local program (stdio) works. In Agents (MCP), pick your client: the app shows the exact settings to paste, with the paths filled in for your computer. They have this shape:

{
  "mcpServers": {
    "ninjasurfer": {
      "command": "<ninjasurfer command-line tool>",
      "args": ["mcp"],
      "env": { "NINJASURFER_API_KEY_FILE": "<path to your agent key file>" }
    }
  }
}

• command is NinjaSurfer's command-line tool, ninjasurfer, which the app installs for you, and args is ["mcp"]. Copy the real path from the app; it differs between Windows, macOS and Linux.
• NINJASURFER_API_KEY_FILE points to a file that holds the key, and the app fills it in when it is needed. Never paste a key value into an agent's settings. On macOS and Linux the file must be readable only by you (chmod 600).

Agents that can't start a program

Turn on Agents (MCP) → Advanced: local HTTP and give the agent the address shown there, or use Copy prompt for the agent on the same card: the prompt already contains the current address. Only programs on this computer can reach it, and only while NinjaSurfer runs.

Check the connection

1. In your agent, ask: “List my NinjaSurfer profiles.”
2. The agent calls the profile_list tool and answers with your profiles, showing which ones are open.
3. In the app, Agents (MCP) shows Last call … and the call under Recent agent activity.

What the agent can do

Tools are grouped by job. The agent chooses them itself; you don't need their names, but you may see them in its replies.

Page model for agents: page_content (Chromium AIPageContent)

page_content gives the agent the page the way Chromium's own AI features see it: one short line per thing that can be used, such as [3]<button> Sign in, with its position. The agent then clicks or types by that number (element). It is the preferred compact view of a page: it is read inside the browser without running anything on the page, so the site cannot notice it. It needs a current NinjaSurfer browser; an older one says so.

With Playwright, the same view is one call:

import { getAIPageContent } from "ninjasurfer";

const { text, elements } = await getAIPageContent(page);
console.log(text);                 // [1]<link> Home  [2]<textbox> Search ...
const box = elements[1].bbox;      // where element 2 is, in CSS pixels
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);

Example requests

Troubleshooting

The agent doesn't list NinjaSurfer or its tools

Restart the agent, or reload its MCP servers, after adding NinjaSurfer: most agents read their settings only at start. Then check Agents (MCP): your agent should show Added. If it doesn't, click Add again.

“Unauthorized” or a 401 error

The agent's access is no longer valid, for example after you signed out or changed accounts. Open Agents (MCP) and click Add again for that agent: it replaces NinjaSurfer's entry. Then restart the agent.

“Profile is open elsewhere”

A profile runs in one place at a time. Close it in the NinjaSurfer app, or in the other program that has it open, and ask again. Or ask the agent to use another profile: profile_list shows which profiles are open.

A start is refused

Starts from an agent follow the same rules as in the app. Check that your plan is active and that the profile starts from the app itself.

“Key file must be readable only by you”

On macOS and Linux, the file named in NINJASURFER_API_KEY_FILE must belong to you and be readable only by you. Run chmod 600 on it, or re-add NinjaSurfer from the app so it writes the file correctly.

Where is the log?

The last calls are under Agents (MCP) → Recent agent activity. The full log is one file per day (audit-YYYY-MM-DD.jsonl), kept for 14 days:

macOS	~/Library/Caches/ninjasurfer/mcp/
Windows	%LOCALAPPDATA%\ninjasurfer\mcp\
Linux	~/.cache/ninjasurfer/mcp/

Privacy and safety

• The MCP server runs on your computer. Your profiles, cookies and pages are not sent anywhere through it.
• Every call is logged locally. The log masks secrets, records cookies by name and site only, and stores at most the first 64 characters of typed text; for password fields it stores only the length.
• Agents act through the same start rules as you do in the app. Disconnect an agent at any time in Agents (MCP) with Remove from ….