Connect through the MCP gateway

eyeball exposes Streamable HTTP MCP at /mcp. Configure a project key and a stable external user ID.

Claude Code#

{
  "mcpServers": {
    "eyeball": {
      "type": "http",
      "url": "http://127.0.0.1:3001/mcp",
      "headers": {
        "Authorization": "Bearer eyeball_dev_project",
        "X-Eyeball-User-Id": "demo_user"
      }
    }
  }
}

Cursor#

{
  "mcpServers": {
    "eyeball": {
      "url": "http://127.0.0.1:3001/mcp",
      "headers": {
        "Authorization": "Bearer eyeball_dev_project",
        "X-Eyeball-User-Id": "demo_user"
      }
    }
  }
}

Search before loading#

Ask the client to call eyeball.search_tools when the full catalog is too large:

{
  "query": "find a recent reservation email and inspect it",
  "limit": 5
}

In search discovery mode, pass the selected card to the always-listed eyeball.execute_tool tool:

{
  "name": "gmail.search_emails",
  "input": {"query": "reservation", "pageSize": 5}
}

Catalog discovery mode lists provider tools directly instead. Mutations use mcp:<session-id>:<json-rpc-id> as their default idempotency key, and terminal responses include _meta["dev.eyeball/execution"]. MCP hosts retain the session ID returned by initialize; callers must not invent one.

Run long-lived tools as Tasks#

Ordinary MCP clients continue to receive terminal tool results. A client that supports the experimental 2025-11-25 Tasks profile opts in during initialization with:

{
  "capabilities": {
    "experimental": {
      "tasks": {}
    }
  }
}

That session discovers async-by-nature tools such as twilio.start_call with execution.taskSupport: "required". Invoke one with a task object, poll its returned exe_* task ID through tasks/get, and retrieve the canonical result through tasks/result. A long-lived GET /mcp SSE connection receives progress and terminal-status notifications while polling remains the source of truth.

See the MCP endpoint contract for SSE framing, Tasks, session headers, and metadata.