Skip to main content
The Kadoa MCP server exposes workflow management tools to AI assistants via the Model Context Protocol. This lets you create, run, and manage web scraping workflows using natural language from your AI assistant. Supported Clients: ChatGPT · Codex · Claude.ai · Claude Code · Claude Desktop · Cursor · Gemini CLI · Any MCP-compatible client

​
Prerequisites

​
Remote Server (no install needed)

A hosted MCP server is available at https://mcp.kadoa.com/mcp. No local install or API key needed — just connect and sign in with your Kadoa account via OAuth. 
claude mcp add kadoa --transport http https://mcp.kadoa.com/mcp

​
Local (stdio)

Install the MCP server locally using npx. This requires an API key.

​
API Key

Get your API key from Settings. The MCP server resolves your key in this order:
  1. KADOA_API_KEY environment variable
  2. ~/.kadoa/config.json (shared with the Kadoa CLI)
If you have the CLI installed, run kadoa login and the MCP server picks up your saved key automatically. 
claude mcp add --transport stdio -e KADOA_API_KEY=tk-your_api_key kadoa -- npx -y @kadoa/mcp

# Add -s user to enable for all projects.
# If you have the Kadoa CLI installed, skip the -e flag —
# just run `kadoa login` and the MCP will use your saved key automatically.

​
Permissions

The tools you can use depend on your team role. Viewers and Compliance Officers have read-only access:
ToolMember / Admin / OwnerViewerCompliance Officer
list_workflows
get_workflow
fetch_data
create_workflow
run_workflow
update_workflow
approve_workflow
delete_workflow
whoami
list_notification_channels
create_notification_channel
delete_notification_channel
list_notification_settings
configure_notifications
delete_notification_setting
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:
ToolDescription
create_workflowCreate an agentic navigation workflow from a prompt
list_workflowsList all workflows with status
get_workflowGet detailed workflow information including prompt, schedules, and notification config
run_workflowExecute a workflow
fetch_dataGet extracted data from a workflow
delete_workflowDelete a workflow
approve_workflowApprove and activate a workflow
update_workflowUpdate workflow configuration and schema
create_realtime_monitorCreate a real-time monitoring workflow
whoamiShow current user details, auth method, and team memberships
team_listList all teams you belong to and see which is active
team_switchSwitch the active team by name or ID
list_notification_channelsList notification channels for a workflow or workspace
create_notification_channelCreate an email, webhook, or Slack notification channel
delete_notification_channelDelete a notification channel
list_notification_settingsList event-to-channel notification mappings
configure_notificationsSet up notifications for workflow events in one step
delete_notification_settingRemove a notification event-to-channel mapping
The status field returned by list_workflows and get_workflow shows the computed workflow state (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 with create_workflow

The create_workflow tool supports an interval parameter to schedule recurring extractions. If omitted, it defaults to ONLY_ONCE. Available intervals: ONLY_ONCE, EVERY_10_MINUTES, HALF_HOURLY, HOURLY, THREE_HOURLY, SIX_HOURLY, TWELVE_HOURLY, EIGHTEEN_HOURLY, DAILY, TWO_DAY, THREE_DAY, WEEKLY, BIWEEKLY, TRIWEEKLY, FOUR_WEEKS, MONTHLY, REAL_TIME, CUSTOM.
REAL_TIME workflows run continuously and cannot be triggered manually via run_workflow.

​
Updating workflows with update_workflow

In addition to the schema, update_workflow accepts the following parameters:
ParameterDescription
descriptionUpdate the workflow description
tagsSet tags for the workflow
userPromptUpdate the extraction prompt
schedulesSet cron expressions (use with CUSTOM interval)
limitSet the maximum number of records to extract
You cannot convert between regular and real-time workflows. Changing a regular workflow’s interval to REAL_TIME or a real-time workflow’s interval to a scheduled value will return an error.

​
Workflow details with get_workflow

The get_workflow tool returns detailed information including:
FieldDescription
promptThe original user-provided navigation prompt
schedulesCron expressions for CUSTOM interval workflows
nextInvocationTimestamp of the next scheduled run
limitMaximum records per run
tagsOrganizational tags
notificationConfigConfigured notification channels and events

​
Notification tools

Six tools let you manage notifications for workflow events directly from your AI assistant. list_notification_channels — List channels for a specific workflow or your entire workspace. create_notification_channel — Create a new channel. Supported types: EMAIL, WEBHOOK, SLACK. Configure with recipients (email), webhook URL and HTTP method (webhook), or Slack integration (Slack). configure_notifications — All-in-one setup: subscribe workflow events to notification channels in a single call. Supports event types like workflow_started, workflow_finished, workflow_failed, workflow_data_change, and more. Pass ["all"] to subscribe to every event. list_notification_settings — View existing event-to-channel mappings, optionally filtered by workflow or event type. delete_notification_channel / delete_notification_setting — Remove channels or event mappings. Both require a two-step confirmation (confirmed: true) to prevent accidental deletion.

​
Usage Examples

Once the MCP server is configured, you can manage the full workflow lifecycle through natural conversation. Here are a few common operations shown as Claude Code sessions.
  • “Create a workflow to extract product prices from example.com”
  • “List my Kadoa workflows”
  • “Run workflow abc123 and show me the results”
  • “Update the schema for workflow abc123 to include a rating field”
  • “Delete workflow abc123”
  • “List my teams”
  • “Switch to the Acme Corp team”
  • “Set up email notifications when workflow abc123 finishes or fails”
  • “Create a Slack channel for all my workflow notifications”
  • “Show me which notifications are configured for workflow abc123”

​
Troubleshooting

“No API key found”
  • Run kadoa login (requires npm install -g @kadoa/cli), or
  • Set KADOA_API_KEY in your MCP config or environment
  • Verify your API key starts with tk-
“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
“getaddrinfo EAI_AGAIN” or network errors in Codex
  • Codex blocks network access by default
  • Enable network_access = true in ~/.codex/config.toml (see Codex tab above)
  • Restart Codex after changing the config