MCP Integration

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:

Method	Header	Use Case
JWT Token	`Authorization: Bearer <token>`	Production
Debug Mode	`X-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

Generate an API token from Zeus Web UI
Configure Cursor’s MCP settings
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.

​Endpoint

​Configuration

​Cursor / Claude Desktop

​Debug Mode

​Available Tools

​desktop_exec

​browser_read

​hitl_prompt

​list_workflows

​execute_workflow

​check_desktop_status

​Authentication

​Architecture

​Example: Using Zeus in Cursor

Endpoint

Configuration

Cursor / Claude Desktop

Debug Mode

Available Tools

desktop_exec

browser_read

hitl_prompt

list_workflows

execute_workflow

check_desktop_status

Authentication

Architecture

Example: Using Zeus in Cursor