Skip to main content
Zeus exposes its Desktop automation capabilities through the Model Context Protocol (MCP), allowing external AI tools like Cursor, Claude Desktop, and other MCP clients to directly leverage Zeus’s powerful desktop automation features.

​
Endpoint

POST /mcp
Zeus provides a Streamable HTTP MCP server that external clients can connect to.

​
Configuration

​
Cursor / Claude Desktop

Add the following to your MCP client configuration: 
{
  "mcpServers": {
    "zeus-desktop": {
      "url": "https://zeus-api.agentspro.cn/mcp",
      "headers": {
        "Authorization": "Bearer <jwt_token>"
      }
    }
  }
}

​
Debug Mode

For local development, enable debug auth by setting MCP_DEBUG_AUTH=true: 
{
  "mcpServers": {
    "zeus-desktop": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-User-Id": "<your_user_id>"
      }
    }
  }
}

​
Available Tools

Once connected, external MCP clients can use these tools:

​
desktop_exec

Execute shell commands on the user’s local machine. 
desktop_exec({
  command: "ls -la",
  cwd: "/path/to/directory",  // optional
  timeout: 60000,             // ms, default 60s
  shell: "bash"               // optional
})
Use cases:
  • File operations: ls, cat, mkdir, mv, cp, rm, find, grep
  • Version control: git status, git add, git commit, git push
  • Package management: npm install, pip install, brew install
  • Programming: python, node, etc.

​
browser_read

Silently extract data from browser pages. 
browser_read({
  profileId: "profile-id",
  action: "text" | "table" | "form" | "screenshot" | "html" | "url",
  selector: ".my-element"  // optional CSS selector
})
Actions:
  • text - Get page or element text content
  • table - Extract table data (returns 2D array)
  • form - Get form field values (key-value pairs)
  • screenshot - Page screenshot (base64 PNG)
  • html - Get HTML source
  • url - Get current page URL

​
hitl_prompt

Request input from the end user (for verification codes, confirmations, etc.). 
hitl_prompt({
  title: "Verification Required",
  message: "Please enter the SMS code",
  timeout: 120,        // seconds
  inputType: "text"
})
Use cases:
  • SMS/email verification codes
  • User confirmation dialogs
  • Dynamic information requests

​
list_workflows

List all published workflow tools on the Desktop. 
list_workflows()
Returns JSON array with each workflow’s:
  • name - Tool name (prefixed with workflow_)
  • description - Tool description
  • inputSchema - Input parameters JSON Schema

​
execute_workflow

Execute a published workflow tool. 
execute_workflow({
  workflow_name: "workflow_search_product",
  variables: '{"query": "phone", "price": "3000"}'  // JSON string
})

​
check_desktop_status

Check if the Desktop App is connected. 
check_desktop_status()
Returns connection status: 
{
  "status": "connected",
  "nodes": 1,
  "node_ids": ["abc12345..."]
}

​
Authentication

The MCP Gateway supports two authentication methods:
MethodHeaderUse Case
JWT TokenAuthorization: Bearer <token>Production
Debug ModeX-User-Id: <user_id>Development (requires MCP_DEBUG_AUTH=true)
JWT tokens are issued by Better Auth and validated using JWKS with 1-hour cache.

​
Architecture

┌─────────────────────────────────────┐
│  External MCP Client                │
│  (Cursor, Claude Desktop, etc.)     │
└─────────────────────────────────────┘
                  │
                  │ Streamable HTTP
                  ▼
┌─────────────────────────────────────┐
│  Zeus MCP Gateway (/mcp)            │
│  - JWT Authentication               │
│  - Tool routing                     │
└─────────────────────────────────────┘
                  │
                  │ WebSocket
                  ▼
┌─────────────────────────────────────┐
│  Zeus Desktop App                   │
│  - Shell execution                  │
│  - Browser automation               │
│  - Workflow engine                  │
└─────────────────────────────────────┘

​
Example: Using Zeus in Cursor

  1. Generate an API token from Zeus Web UI
  2. Configure Cursor’s MCP settings
  3. In Cursor, ask Claude to:
"List files in my project directory using Zeus desktop"
"Take a screenshot of the current browser page"
"Run 'npm install' in my project folder"
Claude will use the Zeus MCP tools to execute these commands on your machine.