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

# MCP Server

> Use Kadoa from ChatGPT, Claude.ai, Claude Code, Cursor, and other MCP clients

The Kadoa MCP server exposes workflow management tools to AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io). This lets you create, run, and manage web scraping workflows using natural language from your AI assistant.

**Supported Clients:** <img src="https://mintcdn.com/kadoa/kBolG4lRj1dG2Dwb/images/clients/chatgpt.ico?fit=max&auto=format&n=kBolG4lRj1dG2Dwb&q=85&s=8c5d0b9509d6e1054ae0208dae42b9d6" width="16" height="16" style={{display: 'inline', verticalAlign: 'middle', margin: '0 2px'}} data-path="images/clients/chatgpt.ico" /> [ChatGPT](https://chatgpt.com) · <img src="https://mintcdn.com/kadoa/A3sRkEG_6lnlmZD1/images/clients/codex.svg?fit=max&auto=format&n=A3sRkEG_6lnlmZD1&q=85&s=18ecfbf1b63415969afdbde43bd368da" width="16" height="16" style={{display: 'inline', verticalAlign: 'middle', margin: '0 2px'}} data-path="images/clients/codex.svg" /> [Codex](https://github.com/openai/codex) · <img src="https://mintcdn.com/kadoa/kBolG4lRj1dG2Dwb/images/clients/claude.ico?fit=max&auto=format&n=kBolG4lRj1dG2Dwb&q=85&s=1614cb374f01cd0663f0dc24da10dcb2" width="16" height="16" style={{display: 'inline', verticalAlign: 'middle', margin: '0 2px'}} data-path="images/clients/claude.ico" /> [Claude.ai](https://claude.ai) · <img src="https://mintcdn.com/kadoa/kBolG4lRj1dG2Dwb/images/clients/claude.ico?fit=max&auto=format&n=kBolG4lRj1dG2Dwb&q=85&s=1614cb374f01cd0663f0dc24da10dcb2" width="16" height="16" style={{display: 'inline', verticalAlign: 'middle', margin: '0 2px'}} data-path="images/clients/claude.ico" /> [Claude Code](https://docs.anthropic.com/en/docs/claude-code) · <img src="https://mintcdn.com/kadoa/kBolG4lRj1dG2Dwb/images/clients/claude.ico?fit=max&auto=format&n=kBolG4lRj1dG2Dwb&q=85&s=1614cb374f01cd0663f0dc24da10dcb2" width="16" height="16" style={{display: 'inline', verticalAlign: 'middle', margin: '0 2px'}} data-path="images/clients/claude.ico" /> [Claude Desktop](https://claude.ai/download) · <img src="https://mintcdn.com/kadoa/kBolG4lRj1dG2Dwb/images/clients/cursor.ico?fit=max&auto=format&n=kBolG4lRj1dG2Dwb&q=85&s=2efac0d0ea0a4b0ae9488564acc5dab6" width="16" height="16" style={{display: 'inline', verticalAlign: 'middle', margin: '0 2px'}} data-path="images/clients/cursor.ico" /> [Cursor](https://cursor.sh) · <img src="https://mintcdn.com/kadoa/kBolG4lRj1dG2Dwb/images/clients/gemini.png?fit=max&auto=format&n=kBolG4lRj1dG2Dwb&q=85&s=f649575ca6bdc0438ae8e646ff0b78ab" width="16" height="16" style={{display: 'inline', verticalAlign: 'middle', margin: '0 2px'}} data-path="images/clients/gemini.png" /> [Gemini CLI](https://github.com/google-gemini/gemini-cli) · Any MCP-compatible client

Here it is in action. Claude creates a workflow from a template and starts it, all from a single message:

<img noZoom src="https://mintcdn.com/kadoa/vSlRUAnAzL74Ur7q/images/assistant/mcp-claude-desktop.png?fit=max&auto=format&n=vSlRUAnAzL74Ur7q&q=85&s=c8d21eefa5e65c987ff3c4132ee7e2f8" alt="Claude using the Kadoa MCP server to create and run a workflow from a template: the tool calls (list templates, get template, create workflow) and the resulting workflow ID, dashboard link, and email notification" width="850" height="1012" data-path="images/assistant/mcp-claude-desktop.png" />

## Setup

A hosted MCP server is available at `https://mcp.kadoa.com/mcp`. No local install needed, just connect and sign in with your Kadoa account via OAuth.

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add kadoa --transport http https://mcp.kadoa.com/mcp
  ```

  ```text ChatGPT theme={null}
  1. Go to Settings → Connectors → Add MCP server
  2. Enter the URL: https://mcp.kadoa.com/mcp
  3. Choose OAuth authentication and sign in with your Kadoa account (Google)
  ```

  ```text Claude.ai theme={null}
  1. Go to Settings → Connectors → Add custom MCP
  2. Enter the URL: https://mcp.kadoa.com/mcp
  3. Sign in with your Kadoa account via OAuth
  ```

  ```json Cursor theme={null}
  // .cursor/mcp.json
  {
    "mcpServers": {
      "kadoa": {
        "type": "http",
        "url": "https://mcp.kadoa.com/mcp"
      }
    }
  }
  ```

  ```json Claude Desktop theme={null}
  // Add to your Claude Desktop config file (create it if it doesn't exist):
  // macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
  // Linux:   ~/.config/Claude/claude_desktop_config.json
  // Windows: %APPDATA%\Claude\claude_desktop_config.json
  {
    "mcpServers": {
      "kadoa": {
        "type": "http",
        "url": "https://mcp.kadoa.com/mcp"
      }
    }
  }
  // Restart Claude Desktop after saving.
  ```

  ```bash Codex theme={null}
  codex mcp add kadoa --url https://mcp.kadoa.com/mcp
  ```

  ```bash Gemini CLI theme={null}
  gemini mcp add -t http kadoa https://mcp.kadoa.com/mcp
  ```

  ```text Any MCP Client theme={null}
  URL: https://mcp.kadoa.com/mcp
  Auth: OAuth
  ```
</CodeGroup>

### Connecting for the first time

When you add the server, your client opens a browser so you can sign in with your Kadoa account and grant access. The connection then stays authorized; if a session expires, your client prompts you to sign in again. There is nothing to install and no API key to manage.

<Note>
  The MCP server acts as you: every tool runs under your Kadoa role and active team, and each action is recorded in the workflow's [history](/docs/workflows/states). For automated or shared agents, connect with a read-only **Viewer** role and switch to a higher-privilege role only when you need write access.
</Note>

## Permissions

The tools you can use depend on your team role. Viewers and Compliance Officers have read-only access:

| Tool                          |        Member / Admin / Owner       |                Viewer               |          Compliance Officer         |
| ----------------------------- | :---------------------------------: | :---------------------------------: | :---------------------------------: |
| `list_workflows`              | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `get_workflow`                | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `get_workflow_history`        | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `fetch_data`                  | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `export_data`                 | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `create_workflow`             | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `run_workflow`                | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `update_workflow`             | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `approve_workflow`            |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  | <Icon icon="check" color="green" /> |
| `pause_workflow`              | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `delete_workflow`             | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `whoami`                      | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `list_notification_channels`  | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `create_notification_channel` | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `delete_notification_channel` | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `list_notification_settings`  | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `configure_notifications`     | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `delete_notification_setting` | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `list_variables`              | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `get_variable`                | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `create_variable`             | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `update_variable`             | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `delete_variable`             | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `create_template`             | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `get_template`                | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `list_templates`              | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `update_template`             | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `delete_template`             | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `create_template_version`     | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `list_template_schemas`       | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `save_workflow_as_template`   | <Icon icon="check" color="green" /> |  <Icon icon="xmark" color="red" />  |  <Icon icon="xmark" color="red" />  |
| `list_changes`                | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |
| `get_change`                  | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> | <Icon icon="check" color="green" /> |

If a tool is not available for your role, you'll receive an error message with instructions to contact your team admin.

## Tools

The server exposes tools covering the full workflow lifecycle, notifications, and team management:

| Tool                          | Description                                                                            |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| `create_workflow`             | Create an agentic navigation workflow from a prompt                                    |
| `list_workflows`              | List all workflows with status                                                         |
| `get_workflow`                | Get detailed workflow information including prompt, schedules, and notification config |
| `get_workflow_history`        | List recent edit-audit entries for a workflow with field-level diffs                   |
| `run_workflow`                | Execute a workflow                                                                     |
| `fetch_data`                  | Get extracted data from a workflow (paginated, with filters and sorting)               |
| `export_data`                 | Export the full extracted dataset as a signed URL, ideal for large workflows           |
| `delete_workflow`             | Delete a workflow                                                                      |
| `approve_workflow`            | Approve and activate a workflow                                                        |
| `pause_workflow`              | Pause an active workflow so it stops running on its schedule                           |
| `update_workflow`             | Update workflow configuration and schema                                               |
| `create_realtime_monitor`     | Create a real-time monitoring workflow                                                 |
| `whoami`                      | Show current user details and team memberships                                         |
| `team_list`                   | List all teams you belong to and see which is active                                   |
| `team_switch`                 | Switch the active team by name or ID                                                   |
| `list_notification_channels`  | List notification channels for a workflow or workspace                                 |
| `create_notification_channel` | Create an email, webhook, Slack, or WebSocket notification channel                     |
| `delete_notification_channel` | Delete a notification channel                                                          |
| `list_notification_settings`  | List event-to-channel notification mappings                                            |
| `configure_notifications`     | Set up notifications for workflow events in one step                                   |
| `delete_notification_setting` | Remove a notification event-to-channel mapping                                         |
| `list_variables`              | List all variables in the current team scope                                           |
| `get_variable`                | Get a specific variable by ID                                                          |
| `create_variable`             | Create a key-value variable (STRING, NUMBER, BOOLEAN, or JSON)                         |
| `update_variable`             | Update a variable's key, value, or data type                                           |
| `delete_variable`             | Delete a variable (two-step confirmation)                                              |
| `create_template`             | Create a reusable template for workflow configurations                                 |
| `get_template`                | Get a template by ID, including all published versions                                 |
| `list_templates`              | List all templates in the current team                                                 |
| `update_template`             | Update a template's name or description                                                |
| `delete_template`             | Delete a template (two-step confirmation)                                              |
| `create_template_version`     | Publish a version with prompt, schema, and notifications                               |
| `list_template_schemas`       | List schemas associated with a template                                                |
| `save_workflow_as_template`   | Create a template from an existing workflow's configuration                            |
| `list_changes`                | List detected data changes across real-time monitoring workflows                       |
| `get_change`                  | Get detailed information about a specific detected change                              |

The `status` field returned by `list_workflows` and `get_workflow` shows the computed [workflow state](/docs/workflows/states) (Complete, Running, Failed, Paused, Scheduled, etc.) rather than just the raw lifecycle state. You can filter with `list_workflows` using the `state` parameter (`ACTIVE`, `FAILED`, `PAUSED`, `PREVIEW`).

### Scheduling

The `create_workflow` tool accepts an `interval` parameter for recurring extractions (defaults to `ONLY_ONCE`). Use `CUSTOM` with cron expressions for fine-grained control. See [Scheduling →](/docs/sdk/workflows/scheduling) for all available intervals and examples.

### Updating workflows

`update_workflow` accepts `description`, `tags`, `userPrompt`, `schedules`, and `limit` in addition to schema changes. See [Manage Workflows →](/docs/sdk/workflows/manage) for details.

### Notifications

Six tools manage notification channels and event subscriptions: `list_notification_channels`, `create_notification_channel`, `delete_notification_channel`, `list_notification_settings`, `configure_notifications`, and `delete_notification_setting`. See [Notifications →](/docs/sdk/notifications/overview) for channel types and setup examples.

### Variables

Five tools manage reusable variables (`@variableKey` syntax in prompts): `list_variables`, `get_variable`, `create_variable`, `update_variable`, and `delete_variable`. See [Variables →](/docs/sdk/variables/overview) for details and examples.

### Templates

Twelve tools manage reusable, versioned workflow configurations: `create_template`, `get_template`, `list_templates`, `update_template`, `delete_template`, `create_template_version`, `list_template_schemas`, `list_template_workflows`, `link_workflows_to_template`, `unlink_workflows_from_template`, `apply_template_update`, and `save_workflow_as_template`. See [Templates →](/docs/sdk/templates/overview) for details and examples.

### Changes

Two tools let you inspect detected data changes from real-time monitoring workflows: `list_changes` returns structured diffs (added, removed, changed records) across one or more workflows, and `get_change` retrieves the full snapshot and diff for a specific change.

### Fetching and exporting data

Two tools retrieve extracted data: use `fetch_data` for paginated reads (default 50 rows, max 500) with `filters`, `sortBy`, and `order`; use `export_data` for the full dataset. It returns a self-authenticating signed URL ideal for Claude for Excel ('Get Data from Web') or pandas/duckdb code execution.

### Workflow history

`get_workflow_history` returns recent edit-audit entries for a workflow with field-level diffs (added, removed, and changed values) so you can see who modified what and when.

## Usage Examples

Once the MCP server is configured, you manage the full workflow lifecycle through natural conversation. A few prompts by area. See the [tools](#tools) above for the full surface:

**Build and run**

* "Create a workflow to extract product prices from [https://sandbox.kadoa.com/ecommerce](https://sandbox.kadoa.com/ecommerce)"
* "Run my 'Product Monitor' workflow and show me the results"

**Manage workflows**

* "Update the 'Product Monitor' schema to add a rating field"
* "Pause the 'Old Scraper' workflow"

**Get data and changes**

* "Export my 'Product Monitor' dataset"
* "Show me recent changes detected by my real-time monitors"

**Notifications, variables, and templates**

* "Email me when 'Product Monitor' finishes or fails"
* "Save my 'Product Monitor' workflow as a template called 'Product Scraper'"

**Teams**

* "List my teams, then switch to Acme Corp"

## Troubleshooting

**"I don't have access to Kadoa"**

* Verify the MCP server is configured in the correct config file
* Restart your MCP client after configuration changes
* Re-authenticate via OAuth if prompted

**"Authentication failed"**

* Your OAuth session may have expired, so re-authenticate when prompted by your MCP client
* If switching teams, verify the team exists with `team_list` before using `team_switch`