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 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.
{
"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.
| Tool | What it does |
|---|---|
open_session | Starts a browser. Takes os, sphynx_id, proxy and start_url |
close_session | Ends the session. Returns an empty result |
navigate | Loads a URL and returns the address, title and http_status |
elements | Lists what can be clicked or filled, or the matches of a locator |
extract | Reads the page as Markdown, text, HTML, links or named selections |
click | Clicks an element |
fill | Sets the value of a field |
type | Types text key by key |
press | Presses one key, such as Enter |
scroll | Scrolls by pixels or to an element |
screenshot | Returns 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:
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.
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
extractreturns 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 passmax_charsfor more.- A session opened by an agent ends like any other. After
idle_timeout_secondswithout a tool call, 300 by default, it closes and the next call fails withsession_closed. - Open sessions count toward the key's concurrency limit. Have the agent call
close_sessionwhen it is done. clicktakes about 1.5 to 4 s, because the pointer moves to the element along a human-like path.typetakes 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_idto 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.
element_not_found: no element matched| Code | When |
|---|---|
invalid_request | A bad argument, two locators on one call, or no session is open and no session_id was passed |
element_not_found | No element matched the locator |
no_page_loaded | The tab is blank. Call navigate first |
session_closed | The session has ended. Call open_session again |
concurrency_limit | Too many live sessions for this key |
navigation_timeout | The page did not finish loading in time |
navigation_failed | DNS 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.