npm package: @kadoa/mcp
Description: Kadoa MCP Server — manage workflows from Claude Desktop, Cursor, and other MCP clients
Latest version: 0.4.1

# Kadoa MCP Server

Use [Kadoa](https://kadoa.com) 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

```bash
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`:

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

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

```bash
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:**

```bash
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