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, no API key config. 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 (Remote)

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.

Local Setup (stdio)

If you prefer to run the MCP server locally (e.g., for development or to use your own API key), install via npx:

Claude Code

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, you can skip the -e flag — just run kadoa login and the MCP will use your saved key automatically.

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kadoa": {
      "command": "npx",
      "args": ["-y", "@kadoa/mcp"],
      "env": {
        "KADOA_API_KEY": "tk-your_api_key"
      }
    }
  }
}

Restart Claude Desktop.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "kadoa": {
      "command": "npx",
      "args": ["-y", "@kadoa/mcp"],
      "env": {
        "KADOA_API_KEY": "tk-your_api_key"
      }
    }
  }
}

Codex

codex mcp add kadoa -- npx -y @kadoa/mcp

Or add to ~/.codex/config.toml:

[mcp_servers.kadoa]
command = "npx"
args = ["-y", "@kadoa/mcp"]

[mcp_servers.kadoa.env]
KADOA_API_KEY = "tk-your_api_key"

Gemini CLI

gemini mcp add -t stdio kadoa npx -- -y @kadoa/mcp

Or add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "kadoa": {
      "command": "npx",
      "args": ["-y", "@kadoa/mcp"],
      "env": {
        "KADOA_API_KEY": "tk-your_api_key"
      }
    }
  }
}

Get Your API Key

Get your API key from kadoa.com/settings.

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 | | 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 | | 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.

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

"No API key found"

• Run kadoa login (requires npm i -g @kadoa/cli), or
• Set KADOA_API_KEY in your MCP config or environment
• API keys start with tk-

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

• Verify the MCP server is configured correctly
• Restart your MCP client

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). You also need a local API key — check your backend seed data or API key table.

Run the MCP server locally:

KADOA_PUBLIC_API_URI=http://localhost:12380 KADOA_API_KEY=tk-your_local_api_key bun src/index.ts

Add as a local MCP in Claude Code (alongside the remote one):

claude mcp add --transport stdio \
  -e KADOA_PUBLIC_API_URI=http://localhost:12380 \
  -e KADOA_API_KEY=tk-your_local_api_key \
  kadoa-local -- bun /path/to/kadoa-mcp/src/index.ts

This registers a kadoa-local server that coexists with the production kadoa server, so you can use both without conflicts (mcp__kadoa__* for prod, mcp__kadoa-local__* for local).

License

MIT