Kadoa MCP Server

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

Remote Server (no install needed)

A hosted MCP server is available at https://mcp.kadoa.com/mcp. Connect from any MCP client — no local install needed. You sign in with your Kadoa account via OAuth.

Claude Code

claude mcp add kadoa --transport http https://mcp.kadoa.com/mcp

ChatGPT

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)

Claude.ai

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

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "kadoa": {
      "type": "http",
      "url": "https://mcp.kadoa.com/mcp"
    }
  }
}

Any MCP Client

Point your client to https://mcp.kadoa.com/mcp with OAuth authentication.

Tools

| 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 | | get_workflow_history | Get the workflow's configuration revision history (audit log) — who changed it, when, from which channel, and a changedFields summary per revision | | run_workflow | Execute a workflow | | fetch_data | Get extracted data from a workflow | | delete_workflow | Delete a workflow | | approve_workflow | Approve and activate a workflow | | pause_workflow | Pause an active workflow | | update_workflow | Update workflow configuration and schema | | whoami | Show current user details, auth method, 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 |

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 and run a workflow

> You: Create a workflow to extract product names, prices, and ratings
        from https://example-shop.com/products

Claude calls create_workflow and returns the workflow ID, proposed
navigation steps, and data schema for your review.

> You: The schema looks good. Approve it and kick off a run.

Claude calls approve_workflow to activate the workflow, then
run_workflow to start extraction.

> You: Is the run done? Show me the results.

Claude checks the run status with get_workflow, then calls fetch_data
to retrieve the extracted records and display them as a table.

Create a workflow from a template

> You: Use my "Product Scraper" template to scrape https://example-shop.com.

Claude calls list_templates to find the matching template, then
create_workflow with `templateId` and `urls` only — the prompt and
schema are inherited from the template version. Returns the workflow
ID for follow-up with get_workflow or fetch_data.

Update a workflow and re-run

> You: List my workflows.

Claude calls list_workflows and shows all workflows with their
current status (complete, running, failed, paused, scheduled, etc.).

> You: Update wf_abc123 — add an "availability" field to the schema
        and rename "cost" to "price".

Claude calls update_workflow with the new schema, confirms the
changes, and shows the updated field list.

> You: Run it again with the new schema.

Claude calls run_workflow and waits for completion, then fetches
the latest data with fetch_data so you can verify the changes.

Monitor and clean up

> You: Show me all active workflows and their last run results.

Claude calls list_workflows, filters to active ones, then calls
fetch_data for each to summarize the latest extraction results.

> You: Delete the ones that haven't produced data in the last week.

Claude identifies stale workflows from the results and calls
delete_workflow for each, confirming before proceeding.

Troubleshooting

Claude says "I don't have access to Kadoa"

• Verify the MCP server is configured correctly
• Restart your MCP client
• Re-authenticate via OAuth if prompted

Deploying the Remote Server

The remote MCP server at mcp.kadoa.com runs as a Docker container on GKE, deployed from the kadoa-backend monorepo.

To deploy a new version:

1. Publish a new @kadoa/mcp version to npm (npm publish)
2. In kadoa-backend, update infra/docker/mcp/package.json to the new version and run bun install to regenerate the lockfile
3. Merge to main — the CI pipeline (main-build-deploy.yml) builds and pushes the Docker image automatically
4. Trigger the Deploy to Production workflow (deploy-prod.yml) with:
   • Target cluster: gcp
   • Deployment scope: mcp
   • Image tag: the tag from step 3 (shown in the build summary)
   • Method: kubectl

Infrastructure files in kadoa-backend:

• infra/docker/mcp/Dockerfile.mcp-server — Docker image definition
• infra/docker/mcp/package.json — pinned @kadoa/mcp version
• infra/cdk8s/mcp/ — Kubernetes manifests (cdk8s)

Development

bun install
bun run dev        # Run locally
bun run test       # Run tests
bun run build      # Build for distribution

Connecting to local services

To develop and test against a local Kadoa backend (instead of the production API), point the MCP at your local public-api service using the KADOA_PUBLIC_API_URI environment variable.

Prerequisites: the public-api service must be running locally (default port 12380).

Run the MCP server locally:

KADOA_PUBLIC_API_URI=http://localhost:12380 bun run dev

The server starts in HTTP mode. You authenticate via OAuth the same way as with the remote server.

License

MIT