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

# Build workflows with MCP

> Connect Claude Code or any MCP client to Champ and let an AI agent build, edit, and test your workflows

Champ exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI agents — Claude
Code, Cursor, or any MCP-compatible client — can work in your Champ workspace directly. A connected agent can
list and read your workflows, create and edit workflow drafts node by node, run and test them, and inspect run
results. Publishing a draft always remains a human action in the dashboard.

## Create an MCP token

1. Go to [**Tokens**](https://dash.champ.ai/app/tokens) in the dashboard (avatar menu → **API/MCP Tokens**).
2. Click **Create Token**, choose the **MCP** scope, and click **Create**.
3. Copy the token immediately — it's shown **once** and cannot be retrieved again. MCP tokens look like
   `mcp_xxxxxxxx…`.

Tokens don't expire; to revoke one, delete it from the Tokens page and any client using it loses access
immediately. The MCP and API scopes are separate — an `api_…` token is rejected by the MCP endpoint and vice
versa.

## Connect a client

The server speaks Streamable HTTP at:

```
https://api.champ.ai/api/external/v1/workflows_mcp
```

authenticated with an `Authorization: Bearer` header carrying your MCP token.

### Claude Code

```bash theme={null}
claude mcp add champ-workflows --transport http "https://api.champ.ai/api/external/v1/workflows_mcp" --header "Authorization: Bearer <YOUR_MCP_TOKEN>"
```

### Other MCP clients

Add this to your client's MCP configuration (for Cursor, `.cursor/mcp.json`; for Claude Code, `.mcp.json` in
your project):

```json theme={null}
{
  "mcpServers": {
    "champ-workflows": {
      "type": "http",
      "url": "https://api.champ.ai/api/external/v1/workflows_mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_MCP_TOKEN>"
      }
    }
  }
}
```

The [Tokens page](https://dash.champ.ai/app/tokens) shows these same snippets pre-filled with a server name
based on your organization.

## What a connected agent can do

Your client discovers the full tool list automatically (in Claude Code, run `/mcp`). The core groups:

| Group               | Tools                                                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read workflows      | `list_workflows`, `get_workflow`, `get_workflow_node`, `list_workflow_tools`, `list_workflow_triggers`                                                                                      |
| Build & edit drafts | `create_workflow`, `create_workflow_draft`, `update_workflow`, `update_workflow_node`, `add_workflow_nodes_and_edges`, `insert_workflow_node`, `remove_workflow_node`, `move_workflow_node` |
| Run & test          | `workflow_runs`, `test_workflow_node`, `node_test_cases`                                                                                                                                    |
| Cases               | `cases`, `case_stats`, `case_reviews`                                                                                                                                                       |

The server also exposes tools for browser profiles, hybrid-browser step building, document and template
handling for Fill nodes, and organization artifacts and memory — the tool descriptions your client fetches are
the authoritative reference.

## How editing works

MCP editing follows the same draft → publish model as the dashboard:

1. **Edits apply to drafts only.** To change a published workflow, the agent first calls
   `create_workflow_draft`, which opens (or reuses) that workflow's draft revision. Brand-new workflows created
   with `create_workflow` start as drafts.
2. **The graph is edited incrementally** — one node or edge at a time — so the agent can read back and verify
   each change.
3. **Test before publishing.** `test_workflow_node` runs a single node in isolation without saving anything;
   `workflow_runs` can execute the full draft as a test run; `node_test_cases` saves repeatable test cases with
   assertions.
4. **Publishing is human-only.** No MCP tool can publish a draft. The agent can pre-fill the commit message
   (`suggested_commit_message` on `update_workflow`), but a person reviews and publishes from the dashboard.

## Token security notes

* An MCP token grants the full tool set, scoped to your organization — there are no per-tool permissions, so
  treat it like a password and store it in a secrets manager.
* Tokens are visible to and deletable by anyone in your organization on the Tokens page.
* Actions taken through a token are attributed to the user who created it.