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/mcpAdd 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 mcp add --transport http sphynx \
"$SPHYNX_URL/mcp" \
--header "Authorization: Bearer $SPHYNX_API_KEY"{
"mcpServers": {
"sphynx": {
"url": "https://YOUR_HOST/mcp",
"headers": {
"Authorization": "Bearer sx_live_..."
}
}
}
}element_not_found: no element matchedSession 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_idandlive_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, andcountryorserver,usernameandpassword. - start_urlstring
Loaded before the call returns. If it does not load, the call fails with
navigation_failedornavigation_timeoutand no session is opened.
- close_session
Ends the session. Returns nothing: an empty result.
- session_idstringdefaultthe current session
{
"os": "mac",
"proxy": { "type": "residential", "country": "us" },
"start_url": "https://example.com/login"
}{
"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,titleandhttp_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 whenselectis given. - selectlist of selections
Named values to pick out:
name,selectororxpath,attr,all. - max_charsintdefault20000
Applied to each format, to
linksas a whole and to eachall: truelist 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
{
"url": "https://example.com/login"
}{
"url": "https://example.com/login",
"title": "Log in",
"http_status": 200
}{
"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
{
"selector": "#email",
"value": "me@example.com"
}{
"text": "Sign in"
}{
"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.
| HTTP | Code | When |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key |
| 429 | mcp_connection_limit | Too many open MCP connections for this key: at most twice its concurrency limit. details.limit says how many. Retry-After is set |