MCP Tools

The hosted unsurf MCP server registers six default tools plus up to two conditional tools. The local stdio server adds two browser-runtime tools.

Tool	Availability
scout	Always
worker	Always
heal	Always
gallery	Always
directory	Requires VECTORS + AI bindings
agent-scout	Requires ANTHROPIC_API_KEY

The separate local stdio server, unsurf-local-mcp, adds two browser-session tools for nearby agents:

Tool	Availability
unsurf_local_sessions	Local only
unsurf_local_execute	Local only

---

unsurf_local_sessions

List attachable page tabs from the local Chrome/CDP runtime that unsurf-local-mcp can drive.

Input

Field	Type	Required	Description
cdpPort	number		DevTools port to inspect. Defaults to 9222.

Output

Field	Type	Description
connected	boolean	Whether the local browser endpoint responded
sessions	array	Attachable page targets with tab id, title, and URL

---

unsurf_local_execute

Execute a small browser action plan against the attached local Chrome runtime. Actions include goto, click, fill, wait, waitFor, snapshot, and screenshot. Set record: true plus task to route the run through unsurf’s recorder.

Input

Field	Type	Required	Description
cdpPort	number		DevTools port to inspect. Defaults to 9222.
actions	array	✅	Ordered browser action plan
record	boolean		Record the run through unsurf
task	string	Required when record=true	Trace/task label
visibility	"private" | "public"		Recording visibility grant policy

---

scout

Explore a website and capture its API endpoints.

Input

Field	Type	Required	Description
url	string	✅	Target URL to scout
task	string	✅	Natural language description of what to find
publish	boolean		Auto-publish the scouted site to the directory after scouting
auth	object		Authentication config
auth.cookies	string		Cookie header value
auth.headers	Record<string, string>		Additional request headers

Output

Field	Type	Description
siteId	string	Unique identifier for the scouted site
endpointCount	number	Number of unique endpoints captured
pathId	string	Replayable navigation path ID
openApiSpec	object	OpenAPI 3.1 specification

Errors

Error	When
BrowserError	Browser container failed to launch or crashed
NetworkError	Target site unreachable
StoreError	Failed to save results to D1/R2

MCP Schema

{
  "name": "scout",
  "description": "Explore a website and capture every API call. Returns captured endpoints with inferred schemas and an OpenAPI spec.",
  "inputSchema": {
    "type": "object",
    "required": ["url", "task"],
    "properties": {
      "url": { "type": "string", "description": "The URL to scout" },
      "task": { "type": "string", "description": "What to look for, e.g. 'find all API endpoints'" },
      "publish": { "type": "boolean", "description": "Auto-publish the scouted site to the directory after scouting" }
    }
  }
}

---

worker

Execute a scouted path or replay a captured API endpoint.

Input

Field	Type	Required	Description
pathId	string	✅	ID of the path to execute
data	Record<string, unknown>		Data to pass to the endpoint
headers	Record<string, string>		Custom headers (Authorization, Cookie, etc.) for authenticated endpoints

Output

Field	Type	Description
success	boolean	Whether execution succeeded
response	unknown	Response body from the target API

Errors

Error	When
NotFoundError	Path ID does not exist
PathBrokenError	Path is broken — target site changed
NetworkError	Target API unreachable
BrowserError	Browser fallback failed

MCP Schema

{
  "name": "worker",
  "description": "Replay a scouted API path directly — no browser needed. Pass the pathId from a scout result. Include headers for authenticated endpoints.",
  "inputSchema": {
    "type": "object",
    "required": ["pathId"],
    "properties": {
      "pathId": { "type": "string", "description": "The path ID from a scout result" },
      "data": { "type": "object", "description": "Data to pass to the endpoint" },
      "headers": { "type": "object", "description": "Custom headers (Authorization, Cookie, etc.) for authenticated endpoints" }
    }
  }
}

---

heal

Re-scout and repair a broken path.

Input

Field	Type	Required	Description
pathId	string	✅	ID of the broken path
error	string		Description of what went wrong

Output

Field	Type	Description
healed	boolean	Whether the path was successfully repaired
newPathId	string	ID of the new path (if changed)

Errors

Error	When
NotFoundError	Path ID does not exist
BrowserError	Re-scout browser failed
NetworkError	Target site unreachable

MCP Schema

{
  "name": "heal",
  "description": "Fix a broken path. Retries with backoff, then re-scouts and patches if needed.",
  "inputSchema": {
    "type": "object",
    "required": ["pathId"],
    "properties": {
      "pathId": { "type": "string", "description": "The broken path ID" },
      "error": { "type": "string", "description": "The error message that caused the break" }
    }
  }
}

---

gallery

Search the API gallery for previously unsurfed sites. Check here before scouting — someone may have already captured the API you need.

Input

Field	Type	Required	Description
query	string		Search term (domain, endpoint path, or description)
domain	string		Exact domain to look up

Output

Field	Type	Description
results	array	Matching gallery entries
total	number	Number of results returned

MCP Schema

{
  "name": "gallery",
  "description": "Search the API gallery for previously unsurfed sites. Check here before scouting — someone may have already captured the API you need.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search term (domain, endpoint path, or description)" },
      "domain": { "type": "string", "description": "Exact domain to look up" }
    }
  }
}

---

directory

Note

Only available when VECTORS and AI bindings are configured.

Fingerprint-first API directory. Look up domains, browse capabilities, inspect endpoints, semantic search, or publish scouted sites. Returns token-efficient fingerprints, not full specs.

Input

Field	Type	Required	Description
action	"fingerprint" | "capability" | "endpoint" | "search" | "publish"	✅	The directory action to perform
domain	string		Domain to look up (required for fingerprint, capability, endpoint)
capability	string		Capability category (required for capability action). One of: auth, payments, content, crud, search, messaging, files, analytics, social, ecommerce, forms, other
method	string		HTTP method (required for endpoint action)
path	string		Endpoint path (required for endpoint action)
query	string		Search query (required for search action)
siteId	string		Site ID from a scout result (required for publish action)

Actions

Action	Required fields	Description	Token cost
fingerprint	domain	Get domain overview	~50 tokens
capability	domain, capability	List endpoints by capability	~200 tokens
endpoint	domain, method, path	Single endpoint detail	~80 tokens
search	query	Semantic search across all APIs	varies
publish	siteId	Add a scouted site to the directory	varies

MCP Schema

{
  "name": "directory",
  "description": "Fingerprint-first API directory. Look up domains, browse capabilities, inspect endpoints, semantic search, or publish scouted sites.",
  "inputSchema": {
    "type": "object",
    "required": ["action"],
    "properties": {
      "action": { "type": "string", "enum": ["fingerprint", "capability", "endpoint", "search", "publish"] },
      "domain": { "type": "string", "description": "Domain to look up" },
      "capability": { "type": "string", "enum": ["auth", "payments", "content", "crud", "search", "messaging", "files", "analytics", "social", "ecommerce", "forms", "other"] },
      "method": { "type": "string", "description": "HTTP method" },
      "path": { "type": "string", "description": "Endpoint path" },
      "query": { "type": "string", "description": "Search query" },
      "siteId": { "type": "string", "description": "Site ID from a scout result" }
    }
  }
}

---

agent-scout

Note

Only available when ANTHROPIC_API_KEY is configured.

LLM-guided exploration — an AI agent clicks, types, and navigates to find more API endpoints than a simple page load.

Input

Field	Type	Required	Description
url	string	✅	The URL to explore
task	string	✅	What to look for and do on the site

Output

Field	Type	Description
steps	array	Sequence of actions the agent took
networkEventsCount	number	Total network events captured
events	array	Captured network events (method, url, status)

MCP Schema

{
  "name": "agent-scout",
  "description": "LLM-guided exploration — an AI agent clicks, types, and navigates to find more API endpoints than a simple page load.",
  "inputSchema": {
    "type": "object",
    "required": ["url", "task"],
    "properties": {
      "url": { "type": "string", "description": "The URL to explore" },
      "task": { "type": "string", "description": "What to look for and do on the site" }
    }
  }
}