SPHYNX
esc
  • Loading
Open console

API reference

MCP tools

The eleven tools the MCP server gives an agent, with their arguments and what they return.

Sphynx runs a remote MCP server over Streamable HTTP. It takes the same API key as the HTTP API and exposes the same operations as tools. The tools are deterministic: no model runs on our side.

Connect

POST/mcp

Add the server to your agent with its URL and the same Authorization header as the HTTP API. Setup for each client is in the MCP guide.

The server remembers one current session per MCP connection. After open_session, session_id is optional on every tool.

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.

A failed tool call returns an MCP tool error. Its text is the error code, a colon and the message. The codes are on Errors.

Claude Code
claude mcp add --transport http sphynx \
  "$SPHYNX_URL/mcp" \
  --header "Authorization: Bearer $SPHYNX_API_KEY"
Cursor · .cursor/mcp.json
{
  "mcpServers": {
    "sphynx": {
      "url": "https://YOUR_HOST/mcp",
      "headers": {
        "Authorization": "Bearer sx_live_..."
      }
    }
  }
}
A failed tool call
element_not_found: no element matched

Session tools

Open a browser session and close it. The session that open_session returns becomes the current session of the connection.

Tools

  • open_session

    Starts a session. Returns session_id, sphynx_id and live_view_url.

    • oswindows, mac or linuxdefaultrandom

      Picks a fingerprint of that operating system. Cannot be combined with sphynx_id.

    • sphynx_idstring

      The identity of an earlier session, to come back as the same device.

    • proxyobject

      The same object as on session create: type, and country or server, username and password.

    • start_urlstring

      Loaded before the call returns. If it does not load, the call fails with navigation_failed or navigation_timeout and no session is opened.

  • close_session

    Ends the session. Returns nothing: an empty result.

    • session_idstringdefaultthe current session
open_session · arguments
{
  "os": "mac",
  "proxy": { "type": "residential", "country": "us" },
  "start_url": "https://example.com/login"
}
open_session · result
{
  "session_id": "sess_9f2c4b1e7a3d4c5f8e6b0a1d2c3e4f50",
  "sphynx_id": "sx_ab12cd34",
  "live_view_url": "https://api.example/.../view?token=..."
}

Page tools

Load a page and read it. These match the HTTP endpoints of the same name.

Tools

  • navigate

    Loads a page. Returns url, title and http_status.

    • urlstringrequired

      The http or https address to load.

    • session_idstringdefaultthe current session
  • elements

    Lists elements on the current page: the interactive ones, or those matching a locator. Returns the element list, as Elements.

    • selector, xpath or textlocator

      At most one. With none, the interactive elements.

    • limitint, 1–300default60
    • session_idstringdefaultthe current session
  • extract

    Reads the page as Markdown, text, HTML or links, or picks out named values. Returns the same fields as Extract.

    • urlstring

      Navigate here first. Leave it out to read the current page.

    • formatslist of markdown, text, html, links

      The default is ["markdown"], or nothing when select is given.

    • selectlist of selections

      Named values to pick out: name, selector or xpath, attr, all.

    • max_charsintdefault20000

      Applied to each format, to links as a whole and to each all: true list as a whole. The HTTP endpoint defaults to 1000000.

    • session_idstringdefaultthe current session
  • screenshot

    Captures the viewport, the full page or one element. Returns an image.

    • full_pagebooldefaultfalse

      Capture the whole page instead of the viewport.

    • selectorstring

      Capture one element, found by CSS selector.

    • xpathstring

      Capture one element, found by XPath.

    • session_idstringdefaultthe current session
navigate · arguments
{
  "url": "https://example.com/login"
}
navigate · result
{
  "url": "https://example.com/login",
  "title": "Log in",
  "http_status": 200
}
extract · arguments
{
  "formats": ["markdown"],
  "select": [
    { "name": "heading", "selector": "h1" }
  ]
}

Action tools

Act on the page. Each tool is one step of Actions and returns the url and title of the page after it ran. The steps take as long as they do there: about 1.5 to 4 s for click, about 0.1 s per character for type.

A locator is exactly one of selector (CSS), xpath or text (visible text, case-insensitive substring). The first match is used.

Tools

  • click

    Moves the pointer to the element and clicks.

    • selector, xpath or textlocatorrequired
    • session_idstringdefaultthe current session
  • fill

    Focuses the field, clears it and sets the value.

    • selector, xpath or textlocatorrequired
    • valuestringrequired
    • session_idstringdefaultthe current session
  • type

    Types key by key with human timing. With a locator it clicks the element first; without one it types into whatever has focus.

    • valuestringrequired
    • selector, xpath or textlocator
    • session_idstringdefaultthe current session
  • press

    Presses one key.

    • keystringrequired

      Enter, Tab, Escape, ArrowDown, Backspace, or a single character.

    • session_idstringdefaultthe current session
  • scroll

    Scrolls by pixels, or scrolls an element into view.

    • delta_yintdefault800

      Pixels to scroll. Negative is up.

    • selector, xpath or textlocator

      Scroll this element into view instead.

    • session_idstringdefaultthe current session
fill · arguments
{
  "selector": "#email",
  "value": "me@example.com"
}
click · arguments
{
  "text": "Sign in"
}
click · result
{
  "url": "https://example.com/dashboard",
  "title": "Dashboard"
}

Errors

The server itself answers with the HTTP error shape: see Errors. Everything else is a tool error.

HTTPCodeWhen
401unauthorizedMissing or invalid API key
429mcp_connection_limitToo many open MCP connections for this key: at most twice its concurrency limit. details.limit says how many. Retry-After is set