Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@surf-mcp navigate to example.com and click the login button"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for visual browser automation via Fara.
Surf provides browser automation through visual grounding - you describe what you see, and it clicks, types, and navigates based on that description. No CSS selectors, no DOM traversal, just natural language.
The core insight: an AI that can see the page doesn't need to parse HTML.
Related MCP server: Cloudflare Playwright MCP
Visual grounding: Click/type by natural language description ("the blue Submit button")
Direct Fara execution: Fara decides the action, we execute it
Autonomous mode: Multi-step goal completion with progress tracking
Multi-server LM Studio: Auto-discovery and failover across GPU servers
Session persistence: Storage state (cookies, localStorage) round-trips through tool calls
Security controls: Domain allowlists, rate limiting, audit logging
surf-mcp is designed for LOCAL use only via stdio transport.
Multi-tenant environments - trust boundary is the machine
Untrusted networks without SSH tunneling
Compliance-sensitive contexts - no formal security audit
Untrusted MCP clients - surf-mcp trusts its client completely
No encryption at MCP protocol level
LLM responses (Fara/Gemini) executed without verification
Browser automation can click/type anything visible
Use SSH as the transport - surf-mcp sees normal stdio:
{
"mcpServers": {
"surf-remote": {
"command": "ssh",
"args": ["-i", "~/.ssh/key", "user@gpu-box", "surf-mcp"]
}
}
}See SECURITY.md for the full threat model and security controls.
Surf uses Fara-7B (Microsoft's agentic vision model) to understand web pages:
sequenceDiagram
participant Client as MCP Client
participant Surf as surf-mcp
participant PW as Playwright
participant Fara as Fara-7B
Client->>Surf: act("click the search button")
activate Surf
Surf->>PW: screenshot()
PW-->>Surf: PNG image
Surf->>Fara: analyze(image, goal)
Note right of Fara: Visual grounding
Fara-->>Surf: FaraToolCall{left_click, [624,280]}
Surf->>PW: click(624, 280)
PW-->>Surf: done
deactivate Surf
Surf-->>Client: Result + new screenshotAction | Description |
| Click at coordinates |
| Double-click at coordinates |
| Type text (optionally at coordinates) |
| Scroll page up/down |
| Press keyboard keys |
| Navigate to URL |
| Task complete signal (agent mode) |
| Wait for page to load |
# Install from source
pip install -e .
# Install Playwright browsers
playwright install chromium
# Optional: Install harness dependencies
pip install -e ".[harness]"Add to your MCP client configuration:
{
"mcpServers": {
"surf": {
"command": "surf-mcp"
}
}
}# Recommended: use docker compose (reads .env automatically)
cp .env.example .env
# Edit .env with your settings
docker compose up
# Or build and run directly (note: --env-file doesn't strip quotes)
docker build -t surf-mcp .
docker run -it --rm \
--add-host=host.docker.internal:host-gateway \
-e LMSTUDIO_SERVERS=default=http://host.docker.internal:1234/v1 \
surf-mcpInteractive UI for testing visual grounding:
cd tools/fara-harness
./run.sh # Linux/Mac
run.bat # WindowsSee tools/fara-harness/CHEATSHEET.md for command reference.
# Create session
session = await mcp.call("session_create", {
"drivers": {
"web": {
"type": "browser",
"headless": False,
"storage_state": saved_state # Optional: restore cookies
}
}
})
# Navigate to page
await mcp.call("goto", {
"session_id": session["session_id"],
"driver": "web",
"location": "https://example.com"
})
# Click element by description
await mcp.call("click", {
"session_id": session["session_id"],
"driver": "web",
"description": "the blue Submit button"
})
# Direct Fara execution (recommended)
await mcp.call("act", {
"session_id": session["session_id"],
"driver": "web",
"goal": "type 'hello world' into the search box"
})
# Autonomous multi-step execution
await mcp.call("act_autonomous", {
"session_id": session["session_id"],
"driver": "web",
"goal": "log in with username 'demo' and password 'demo123'"
})
# Destroy session and capture storage_state
result = await mcp.call("session_destroy", {"session_id": session["session_id"]})
saved_state = result["summary"]["web"]["storage_state"]# Multi-server LM Studio (visual grounding)
LMSTUDIO_SERVERS="rtx3090=http://localhost:1234/v1,rtx8000=http://192.168.1.100:1234/v1"
FARA_MODEL_IDS="microsoft_fara-7b,fara-7b-gguf,gao-zijian/fara-7b"
FARA_MAX_FAILURES=2
FARA_PROBE_TIMEOUT=2.0
# Confidence and Agent Mode
FARA_MIN_CONFIDENCE=0.7
FARA_CONFIDENCE_RETRIES=2
FARA_MAX_AGENT_STEPS=20
# Alternative: Single OpenAI-compatible endpoint
OPENAI_API_KEY=lm-studio
OPENAI_BASE_URL=http://localhost:1234/v1
SURF_LLM_MODEL=microsoft_fara-7b
# Alternative: Gemini
GOOGLE_API_KEY=...
SURF_LLM_PROVIDER=gemini
SURF_LLM_MODEL=gemini-2.0-flash
# Browser defaults
SURF_BROWSER_HEADLESS=true
SURF_BROWSER_VIEWPORT_WIDTH=1920
SURF_BROWSER_VIEWPORT_HEIGHT=1080
# Session management
SURF_MAX_SESSIONS=10
SURF_SESSION_TIMEOUT_SECONDS=3600Surf supports multiple LM Studio instances for redundancy:
LMSTUDIO_SERVERS="gpu1=http://localhost:1234/v1,gpu2=http://192.168.1.50:1234/v1"Behavior:
Auto-discovery: Probes each server's /v1/models to find loaded Fara model
Prefer loaded: Prioritizes servers with Fara already in VRAM
Failover: Automatically retries on another server if one fails
Tool | Description |
| Create browser session |
| Cleanup session, returns storage_state |
| List active sessions |
Tool | Description |
| Navigate to URL |
| Get current URL |
| Navigate history |
| Get navigation history |
Tool | Description |
| Extract page links |
| Read page content |
| Capture screenshot |
Tool | Description |
| Find element by description, return coordinates |
| Click element by description |
| Type into element by description |
| Scroll page up/down |
| Wait for element or delay |
| Direct Fara execution - Fara decides the action |
| Multi-step autonomous execution until task complete |
See docs/ARCHITECTURE.md for detailed architecture documentation.
Design decisions are recorded in docs/adr/.
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest # All tests
pytest -m "not live" # Skip LLM tests (for CI)
pytest -m live # Only live LLM tests
# Type checking
mypy src/
# Linting
ruff check src/MIT
© 2025 Shane V Cantwell | reflectiveattention.ai
Execute a goal using direct Fara visual grounding. Fara decides what action to take (click, type, scroll, etc.) based on the goal and screenshot.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | Natural language goal (e.g., 'click the search button', 'type hello into the email field') | |
| driver | Yes | Driver alias (must be browser) | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It mentions that Fara uses a screenshot and decides the action, but lacks details on failure modes, prerequisites, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose and behavior with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the sibling tools and no output schema, the description sufficiently explains the tool's role for an AI agent, though it could benefit from more detail on return values or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are described in the schema, and the description adds no extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Execute' and the resource 'goal using direct Fara visual grounding', distinguishing it from sibling tools like click or type by emphasizing that Fara decides the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use act (for autonomous action selection) but does not explicitly state when to prefer it over specific actions like click or type, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a goal autonomously with multiple steps. Fara loops until task completion (terminate action) or max steps reached.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | Natural language goal to achieve autonomously | |
| driver | Yes | Driver alias (must be browser) | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses looping behavior and termination condition, which is helpful. However, lacks details on side effects, failure modes, or safety considerations. Without annotations, more context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence. Not wordy, but includes a minor typo ('Fara' instead of likely 'Fara' or 'Far'). Front-loads the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an autonomous multi-step tool with no output schema and no annotations, the description is too brief. It omits failure handling, max steps details, and expected outcomes, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add additional semantics to parameters beyond what the schema provides, but the schema descriptions are adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a goal autonomously with multiple steps, looping until completion or max steps. This distinguishes it from sibling tools like 'act' which likely handles single actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description only explains what it does, not the context of use or when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Navigate back in history
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fails to disclose behavioral traits like whether it waits for page loads, handles empty history, or requires specific permissions. The minimal text does not fill this gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, efficiently conveying the core purpose. However, it could be slightly expanded for clarity about behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description covers the basic purpose but lacks behavioral context and differentiation from sibling navigation tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to add param details. It adds no extra meaning beyond the schema descriptions, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Navigate back in history' clearly states the action (navigate back) and resource (history). It effectively distinguishes from siblings like 'forward' and 'goto', though it could be more specific (e.g., 'previous page').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'goto' or 'forward'. The description lacks explicit context for usage conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Click UI element by description (browser driver only)
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias (must be browser) | |
| session_id | Yes | Session ID | |
| description | Yes | Natural language description of element to click |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as what happens if the element is not found, whether it waits for the element, or whether it clicks the first match. The description is too brief for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and efficient. However, it may be too concise, lacking important details, so it does not achieve a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and three required parameters, the description should provide more context such as return values, error behavior, or additional constraints. The current description is insufficient for an AI agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meaning all parameters have descriptions in the schema. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'click', the resource 'UI element', and the method 'by description'. It also restricts usage to 'browser driver only', which distinguishes it from non-browser tools. However, it could be more explicit about the natural language element description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions 'browser driver only' but provides no guidance on when to use this tool versus siblings like 'act' or 'type'. It lacks explicit usage context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current location for a driver
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description should cover behavioral aspects. It fails to mention read-only nature, expected latency, or error conditions like missing driver.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded. However, it lacks any structure or additional details that could be included without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing details about output format (coordinates, address), required permissions, or behavior when driver is not in session. As a location tool, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes both parameters with clear names and descriptions. Description adds no extra meaning beyond the purpose, but baseline is 3 due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'current location' for a driver. It differentiates from siblings by focusing on current location, but doesn't explicitly distinguish from 'locate' or other navigation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'locate' or 'list'. Missing context about prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Navigate forward in history
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states basic action; no disclosure of behavior at history boundaries, side effects, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence, no fluff. However, it is under-specified; conciseness should not come at the expense of missing critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema and annotations. Does not describe return values, error conditions, or behavior beyond the basic action. Incomplete for a navigation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description does not need to add parameter details. Baseline 3 is appropriate as description adds no additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'navigate forward in history' with a specific verb and resource. However, it does not explicitly differentiate from the sibling 'back' tool, though the direction is implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'back' or 'history'. No conditions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Navigate to a location (path for filesystem, URL for browser)
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias (e.g., 'fs', 'web') | |
| location | Yes | Target location (path or URL) | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It fails to mention side effects like history management, state changes, or error handling, which are critical for a navigation tool amidst siblings that imply a navigation stack.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no redundancy; every word serves a purpose. However, it could be restructured to front-load the tool's core function more explicitly, which it does moderately well.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and the complexity of navigation (history, errors), the description is insufficient. It does not explain return values, behavior for invalid locations, or interaction with sibling tools like history or session state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds marginal value by clarifying the location parameter type ('path for filesystem, URL for browser'), but does not elaborate on driver aliases or session_id usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Navigate to a location') and provides examples differentiating filesystem paths and URLs. It distinguishes from sibling tools like back/forward by implying direct navigation, but does not explicitly contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use goto versus alternatives such as back, forward, or current. The description does not specify prerequisites or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get navigation history for a driver
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully convey behavioral traits. It does not state whether the tool is read-only, what data is returned, or any side effects. The description is too minimal to aid an agent in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundancy. It is appropriately sized for a simple tool, though it could include more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity and 100% schema coverage, the description lacks crucial context such as what the navigation history contains (e.g., timestamps, locations) and the format of the response. Given no output schema, the description should explain the return value, which it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters ('Driver alias' and 'Session ID'). The tool description adds no additional semantic value beyond the schema, placing it at baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves navigation history for a driver. The verb 'get' and resource 'navigation history' are specific. While it does not explicitly distinguish from sibling tools like 'current' or 'list', the unique function of retrieving historical data sets it apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'current' for immediate state or 'list' for other data. There are no usage conditions, exclusions, or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contents at current location (directory entries for filesystem, links for browser)
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must reveal behavioral traits. It implies a safe read operation and gives examples, but does not disclose pagination, idempotency, error conditions, or required permissions. It is adequate but lacks full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose with no unnecessary words. It is front-loaded and highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with well-defined parameters and no output schema, the description is adequate. It explains the meaning of 'contents' with examples. However, it could hint at return format or depth of listing for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds no extra meaning to the parameters 'driver' and 'session_id' beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'contents at current location', and provides concrete examples ('directory entries for filesystem, links for browser'). This distinguishes it from sibling tools like 'current' or 'read'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of when not to use it or which other tools might be more appropriate for different tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Locate UI element by natural language description (browser driver only)
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias (must be browser) | |
| session_id | Yes | Session ID | |
| description | Yes | Natural language description of element (e.g., 'the blue Submit button') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It only mentions a constraint (browser driver only) but omits side effects, error handling (e.g., element not found), return format, or whether it modifies state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the purpose. It is concise, though it might be too brief to be fully helpful without additional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, no output schema, and 18 sibling tools, the description lacks details like return value (e.g., element identifier or coordinates) and how to use the located element with other tools. This gap reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning beyond the schema, such as usage nuances or format constraints, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Locate', the resource 'UI element', and the method 'by natural language description'. It also specifies the constraint 'browser driver only', which distinguishes it from sibling tools that operate on other or no specific driver.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like 'click' or 'read'. It implies it's for locating elements by descriptions but provides no when-not-to-use or alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read content (file for filesystem, page text for browser)
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias | |
| target | No | Target to read (filename for filesystem, CSS selector for browser) | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'read content' without disclosing any behavioral traits such as side effects, required permissions, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, and contains no filler. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of output schema, the description is minimally adequate. However, it does not describe return format or error handling, which could be inferred but not explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds marginal value by clarifying the target parameter context (file vs CSS selector) but does not go beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads content with specific contexts: filesystem for files and browser for page text. It distinguishes itself from siblings like 'list' and 'click'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading content but does not explicitly provide when to use or when not to use it compared to alternatives like 'list' or 'current'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scroll page (browser driver only)
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Pixels to scroll (default: viewport height) | |
| driver | Yes | Driver alias (must be browser) | |
| direction | No | Scroll direction | down |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as whether scrolling waits for rendering, if it's smooth or instant, or if it triggers any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short with no waste, but it lacks detail. It is front-loaded but incomplete, earning a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (scroll amount, direction) and no output schema, the description should explain behavior and return value, but it does not. Incomplete for an action with multiple parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions. The tool description adds no additional semantic value beyond the schema, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Scroll page' and restricts usage to 'browser driver only', which distinguishes it from sibling navigation tools like 'goto', 'click', etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'act_autonomous' or keyboard actions. The only hint is 'browser driver only' but no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new navigator session with one or more drivers
| Name | Required | Description | Default |
|---|---|---|---|
| drivers | Yes | Driver configurations keyed by alias |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only says 'create a new navigator session', but does not address side effects (e.g., what happens if session exists), required permissions, or state changes beyond creation. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no unnecessary words. However, it could include additional context (e.g., that session is the foundation for navigation) without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool creates a stateful session with nested object parameters and no output schema, the description is incomplete. It does not mention return values, behavior on duplicate creation, or typical usage flow. The complexity of the input schema warrants more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the tool description adds no extra meaning beyond the schema. The 'drivers' parameter description in the schema is adequate, but the tool description itself does not enrich parameter understanding. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'navigator session', with the specific differentiator 'with one or more drivers'. This effectively distinguishes it from sibling tools like session_destroy and session_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The sibling tools (e.g., act, goto) suggest different use cases, but the description does not clarify when session_create is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Destroy a session and cleanup all its drivers
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID to destroy |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context by mentioning 'cleanup all its drivers', but it does not disclose error handling, reversibility, or other side effects. With no annotations, the description carries the full burden and is moderately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, efficiently communicating the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destruction tool with one parameter and no output schema, the description is fairly complete. It could optionally note return behavior but is sufficient as is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes session_id as 'Session ID to destroy' with 100% coverage. The description adds no additional parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Destroy a session and cleanup all its drivers' clearly specifies the verb 'destroy' and the resource 'session', and distinguishes the tool from siblings like session_create and session_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description only states the action without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active sessions
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'List all active sessions' without disclosing behavioral traits such as authentication requirements, definition of 'active', or whether it affects state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is appropriately front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain return values or format. It does not, leaving the agent without information on what the output contains. The tool is simple, but completeness is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters and schema coverage is 100%, so the baseline is 4. The description correctly does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all active sessions', which clearly indicates the verb (list) and resource (active sessions). It implicitly distinguishes from sibling tools like session_create and session_destroy, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. No context or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture current state (JSON for filesystem, PNG screenshot for browser)
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias | |
| session_id | Yes | Session ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It only mentions output formats but does not disclose side effects, permissions, or whether the snapshot is destructive or read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb. However, it could be slightly more structured to explain the driver dependency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the conditional output (JSON vs PNG) based on driver, and no output schema, the description is incomplete. It does not specify which driver values lead to which format or potential errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no additional meaning beyond what is already in the schema (driver alias, session ID). Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool captures the current state and mentions output formats (JSON for filesystem, PNG for browser), but it does not distinguish from sibling tools like 'current' which might also return state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'current' or 'read', and lacks any when-not-to-use or prerequisite information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Type text into UI element by description (browser driver only)
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text to type | |
| driver | Yes | Driver alias (must be browser) | |
| session_id | Yes | Session ID | |
| clear_first | No | Clear existing content before typing | |
| description | Yes | Natural language description of input element |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It does not disclose behaviors such as handling of special keys, element not found errors, or whether the tool waits for the element. The description is too brief for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the core action. However, it could include a bit more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description is insufficient. It does not explain return values, error handling, or prerequisites for the session/driver. A more complete description is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema (only stating 'by description'). It does not explain parameter details like the format of 'description' or behavior of 'clear_first'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Type', the resource 'UI element', and the method 'by description'. It also specifies it's for browser driver only, which helps differentiate from potential similar tools. Among siblings, there is no other typing tool, so purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for browser automation via 'browser driver only', but does not explicitly state when to use this tool versus alternatives like 'click' or 'act'. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for element or delay (browser driver only)
| Name | Required | Description | Default |
|---|---|---|---|
| driver | Yes | Driver alias (must be browser) | |
| seconds | No | Delay in seconds | |
| session_id | Yes | Session ID | |
| description | No | Element to wait for (polls until visible) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It discloses that element waiting 'polls until visible' and that seconds creates a delay. However, it omits behavior for missing elements (timeout), error handling, side effects, and whether both parameters can be used together. The constraint 'browser driver only' is useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that front-loads the core purpose ('wait for element or delay') and appends the essential constraint. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with 4 parameters and no output schema. Description covers two main modes but lacks details on timeout behavior, mutual exclusivity of seconds and description, and return value. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter already described. The description adds minimal value: it re-emphasizes the delay semantics for 'seconds' and specifies polling for 'description'. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'wait' and the two possible targets: 'element' or 'delay', with a specific constraint 'browser driver only'. This distinguishes it from sibling tools like click or goto, which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for waiting, but provides no explicit guidance on when to use wait versus sibling tools (e.g., when to use poll vs delay, or when network waits are needed). No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.5.0actact_autonomousbackclickcurrentforwardgotohistorylistlocatereadscrollsession_createsession_destroysession_listsnapshottypewaitMost tools have distinct purposes (navigation, UI actions, session management), though 'act' and 'act_autonomous' could be confused without reading descriptions. Overall well-differentiated.
Naming is inconsistent: some tools use single verbs ('back', 'click'), others use verb_noun ('session_create'), and some are adjectives ('current') or adverbs ('forward'). No clear pattern.
18 tools is well-scoped for a navigation/UI automation server covering both browser and filesystem. Each tool serves a clear role without being excessive.
Covers core navigation, UI interaction, session management, and state reading. Minor gaps like missing 'refresh' or 'stop' actions, but the tool surface feels solid for its domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
AI-powered web automation. Navigate websites using AI agents for one page or a thousand
AI-powered web automation. Navigate websites using AI agents for one page or a thousand
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shanevcantwell/surf-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
