Browser

Oya Browser docs

MCP setup for Claude Code, Cursor and Codex

Connect Oya Browser to Claude Code, Cursor, Codex, claude.ai, Claude Desktop or the Oya desktop app as an MCP server, through one endpoint that starts browsers itself.

MCP Setup

One endpoint for everything you have. It starts browsers itself, so there is no id to look up first:

Example
https://oyabrowser.com/mcp/pool

Thirty-two tools: twenty-nine that act on a page, round-robined across your browsers, plus start_browser, stop_browser and pool_status. Tab tools, read_elements, read_console, read_network and the browser-specific tools marked in More tools are not on this endpoint; to use those, point at one browser instead, /mcp/{BROWSER_ID}, with the id from the dashboard.

/mcp/pool answers initialize and tools/list without a key, so an agent can list the tools before you sign in. Calls return 401 until you do. For everything an agent needs in one page, point it at oyabrowser.com/llms.txt.

Desktop app

Install the desktop app, then click Connect next to your agent's name in the Oya window footer. Claude Code, Codex, Cursor and VS Code appear there when installed. Connect writes an MCP server named oya-browser at http://127.0.0.1:47321/mcp into that agent's config; Claude Code also gets Oya's tools allowed without prompts. Start a new session and the tools are there. No account, no key.

Cursor

Add to .cursor/mcp.json in your project, or let the desktop app write it for you with Connect:

Example
{
  "mcpServers": {
    "oya-browser": {
      "url": "https://oyabrowser.com/mcp/pool",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Code

On a machine with no Oya app, add the cloud endpoint with Claude Code's own CLI:

Terminal
claude mcp add --transport http oya https://oyabrowser.com/mcp/pool \
  --header "Authorization: Bearer $OYA_API_KEY"

Or install the plugin, which brings the MCP server and a skill that teaches the workflow:

Terminal
claude plugin marketplace add OyadotAI/oya-browser
claude plugin install oya-browser@oya

# any agent that reads skills, without the plugin:
npx skills add OyadotAI/oya-browser

Codex

Codex reads ~/.codex/config.toml. This is the section the desktop app writes; swap the URL and token for the cloud endpoint and your key when there is no desktop:

~/.codex/config.toml
[mcp_servers.oya-browser]
url = "https://oyabrowser.com/mcp/pool"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }
default_tools_approval_mode = "approve"

claude.ai and Claude Desktop

On a Pro, Max, Team or Enterprise plan you need no API key. Open Settings, then Connectors, then Add custom connector, paste https://oyabrowser.com/mcp/pool, and sign in to Oya when asked. Pick the project to connect and allow it. The Claude plan pays for the model; Oya is the browser. The connection shows as a credential in the project's settings, where it can be revoked. Any MCP client that signs in with OAuth works the same way.

Try it

Paste one of these into your agent. Each one proves a different part of the setup.

Works with the desktop app connected or the cloud endpoint configured.

Prompt 1 · any agent
Read https://oyabrowser.com/llms.txt, install Oya on this computer and set yourself up to browse the web through it instead of Chrome. Tell me when you need me to click Connect, then open https://news.ycombinator.com in Oya and read me the top three titles.

Expected: the agent installs and opens Oya, asks you for the Connect click, then reads the three Hacker News titles from Oya.

Add https://oyabrowser.com/mcp/pool as a connector with no key, then:

Prompt 2 · connector, no key
List every tool the Oya connector offers and what each one does. Do not call any of them yet.

Now call pool_status.

Expected: all 32 tools listed without signing in, then a sign-in prompt on pool_status.

Prompt 3 · human handback
Using Oya only, sign in to my GitHub notifications page, tell me how many unread notifications I have, then stop and hand the tab back to me.

Expected: Oya opens GitHub, the agent reports the unread count, then the tab returns to you.