> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Connect external AI tools to Zeus via Model Context Protocol

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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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.

```typescript theme={null}
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.

```typescript theme={null}
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.).

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
execute_workflow({
  workflow_name: "workflow_search_product",
  variables: '{"query": "phone", "price": "3000"}'  // JSON string
})
```

### check\_desktop\_status

Check if the Desktop App is connected.

```typescript theme={null}
check_desktop_status()
```

Returns connection status:

```json theme={null}
{
  "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`) |

<Note>
  JWT tokens are issued by Better Auth and validated using JWKS with 1-hour cache.
</Note>

## 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.