SPHYNX
esc
  • Loading
Open console

Guides

Connect your Agent (MCP)

Add the MCP server to Claude Code or Cursor and your agent gets a browser as tools.

At the end your agent can open a session, load pages, read them, click, fill forms and take screenshots as tool calls. You need an API key and an MCP client such as Claude Code or Cursor.

How it connects

The MCP server is remote. It speaks Streamable HTTP at /mcp on the same base URL as the API and takes the same API key in the Authorization header. There is nothing to install or run locally.

The tools are deterministic. No model runs on the server: your agent's model decides which tool to call, and each tool does one browser operation.

Claude Code

Add the server from a shell that has SPHYNX_URL and SPHYNX_API_KEY set.

Claude Code
claude mcp add --transport http sphynx "$SPHYNX_URL/mcp" \
  --header "Authorization: Bearer $SPHYNX_API_KEY"

claude mcp list then shows sphynx among the servers.

Cursor

Add the server to .cursor/mcp.json in your project. Replace YOUR_HOST and the key with your own.

.cursor/mcp.json
{
  "mcpServers": {
    "sphynx": {
      "url": "https://YOUR_HOST/mcp",
      "headers": { "Authorization": "Bearer sx_live_..." }
    }
  }
}

Other clients

Any client that supports remote servers over Streamable HTTP works. Give it the URL $SPHYNX_URL/mcp and the header Authorization: Bearer $SPHYNX_API_KEY.

What the agent gets

Eleven tools. They are the same operations as the HTTP API, one per tool.

ToolWhat it does
open_sessionStarts a browser. Takes os, sphynx_id, proxy and start_url
close_sessionEnds the session. Returns an empty result
navigateLoads a URL and returns the address, title and http_status
elementsLists what can be clicked or filled, or the matches of a locator
extractReads the page as Markdown, text, HTML, links or named selections
clickClicks an element
fillSets the value of a field
typeTypes text key by key
pressPresses one key, such as Enter
scrollScrolls by pixels or to an element
screenshotReturns an image of the viewport, the full page or one element

The server remembers one current session per MCP connection, so session_id is optional on every tool after open_session. Arguments and return values: MCP tools.

An example

Ask the agent for something that needs a browser:

Prompt
Open example.com/products and tell me which product is the cheapest.

These are the tool calls it can make to answer, with what each returns.

Tool calls
open_session   {"os": "mac"}
  -> {"session_id": "sess_9f2c...", "sphynx_id": "sx_ab12cd34",
      "live_view_url": "https://api.example/v1/sessions/sess_9f2c.../view?token=..."}

navigate       {"url": "https://example.com/products"}
  -> {"url": "https://example.com/products", "title": "Products", "http_status": 200}

extract        {"formats": ["markdown"]}
  -> {"url": "https://example.com/products", "title": "Products",
      "markdown": "# Products\n\n| Product | Price | Stock |\n...",
      "truncated": false}

close_session  {}

The agent reads the table in the Markdown and answers. open_session also returns a live_view_url: ask the agent to print it and open it in a browser to watch the session while it works.

Limits to know

  • extract returns at most 20000 characters per format by default over MCP. The HTTP default is 1000000. Every character lands in the agent's context, so the MCP default is lower. The agent can pass max_chars for more.
  • A session opened by an agent ends like any other. After idle_timeout_seconds without a tool call, 300 by default, it closes and the next call fails with session_closed.
  • Open sessions count toward the key's concurrency limit. Have the agent call close_session when it is done.
  • click takes about 1.5 to 4 s, because the pointer moves to the element along a human-like path. type takes about 0.1 s per character.
  • A key can hold at most twice its concurrency limit in open MCP connections. One more answers 429 mcp_connection_limit.
  • A connection with no request for an hour is dropped. The client initializes again and passes session_id to keep using a session that is still open.

What can go wrong

If the key is missing or invalid, the client cannot connect: the server answers 401 unauthorized. With too many open connections for the key it answers 429 mcp_connection_limit.

A failed tool call returns an MCP tool error whose text is <code>: <message>, with the same codes as the HTTP API. The agent sees the text and can react to it.

A tool error
element_not_found: no element matched
CodeWhen
invalid_requestA bad argument, two locators on one call, or no session is open and no session_id was passed
element_not_foundNo element matched the locator
no_page_loadedThe tab is blank. Call navigate first
session_closedThe session has ended. Call open_session again
concurrency_limitToo many live sessions for this key
navigation_timeoutThe page did not finish loading in time
navigation_failedDNS failure, connection refused, TLS error

Every code: Errors.

Next

  • MCP tools: every tool with its arguments and return value.
  • Agent runs: hand over a task and let a hosted agent drive the session.
  • Concepts: locators, session lifetime and identities.