MCP Setup

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools. CUP ships with a built-in MCP server that exposes 9 tools for UI perception and interaction.

Start the server

cup-mcp
# or
python -m cup.mcp

npx cup-mcp

Configure your agent

Add CUP to your agent's MCP configuration file (.mcp.json, mcp_config.json, etc.):

{
  "mcpServers": {
    "cup": {
      "command": "cup-mcp",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "cup": {
      "command": "npx",
      "args": ["cup-mcp"]
    }
  }
}

Compatible agents

CUP's MCP server works with any MCP-compatible agent:

Advanced configuration

Web platform (CDP)

To capture Chrome/Chromium pages, see Web platform setup for launching Chrome with remote debugging, then configure the MCP server:

{
  "mcpServers": {
    "cup": {
      "command": "cup-mcp",
      "args": ["--platform", "web", "--cdp-port", "9222"]
    }
  }
}

Verbose mode

For debugging, enable verbose output:

{
  "mcpServers": {
    "cup": {
      "command": "cup-mcp",
      "args": ["--verbose"]
    }
  }
}

Best practices

Minimize token usage

• Use find() to locate elements instead of repeatedly calling snapshot()
• Use overview() (instant) to discover apps before snapshot_app()
• Use screenshot() only when you need visual context the tree doesn't capture

Workflow

For the typical agent workflow (snapshot → find → action → verify), see the Quick Start.