MCP server

Kovca has a remote Model Context Protocol server, so AI agents such as Claude Code, Cursor, and VS Code can work with your workspace: find nodes, create and edit workflow drafts, test them, publish them, and run them. It uses the same drafts, validation, publishing, and runs as the Studio and the Workflows API, so everything an agent does shows up in the Studio, and runs are billed and limited exactly like API calls.

POST https://kovca.io/api/v1/mcp
Authorization: Bearer $KOVCA_API_KEY

It uses Streamable HTTP without sessions (JSON responses, no server-sent event stream). Authenticate with a workspace API key as a bearer token. Temporary Instant Workflow keys can't use it.

Access

The key's access level decides which tools the agent sees and can call. A tool above the key's level answers INSUFFICIENT_ACCESS; create a key with the access you need on the API keys page.

Connect a client

claude mcp add --transport http kovca https://kovca.io/api/v1/mcp \
  --header "Authorization: Bearer $KOVCA_API_KEY"

{
  "servers": {
    "kovca": {
      "type": "http",
      "url": "https://kovca.io/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:kovca-api-key}" }
    }
  },
  "inputs": [{ "type": "promptString", "id": "kovca-api-key", "description": "Kovca API key", "password": true }]
}

{
  "mcpServers": {
    "kovca": {
      "url": "https://kovca.io/api/v1/mcp",
      "headers": { "Authorization": "Bearer kvc_..." }
    }
  }
}

Hosted clients that require OAuth sign-in can't connect yet; use a client that sends a bearer header.

Tools

With Run access:

• list_workflows: the workspace's workflows with their latest version and draft revision.
• get_workflow: published versions and their input and output schemas (with Author access, also the draft, its revision, and its validation issues).
• run_workflow: runs a published version, like POST /v1/workflows/{id}/execute, with an optional version and idempotency_key. Actions run for real.
• get_run: a run's status and steps, like GET /v1/runs/{id}.
• The workflows you expose as their own tools (below).

With Author access, also:

• list_templates, list_nodes, get_node_spec: templates, nodes, and each node's input, output, and config schemas.
• list_connectors, list_connections: apps with their triggers and actions, and the workspace's connections and app accounts (IDs and names only).
• connect_app: starts connecting (or reconnecting) an app account. It returns a link to the Connections page, where you click Connect and approve access in the app; the agent then finds the new account with list_connections. Agents never see the account's tokens.
• create_workflow: a new draft, blank, from a template, or around one Decision AI node.
• edit_workflow: applies a batch of edit operations to the draft at base_revision, all or nothing, and returns the remaining issues.
• use_node_version: pins a draft to another version of a node, such as one you just published.
• validate_workflow: validation issues and what blocks publishing.
• test_workflow: runs the draft like a Studio test. AI steps are billed; HTTP and app actions return their samples unless live_actions is true.
• list_custom_nodes, get_custom_node, create_custom_node, edit_custom_node, test_custom_node: the workspace's own Decision AI and Generative AI nodes.

With Publish access, also:

• publish_workflow, publish_custom_node: publish the draft at base_revision as the next immutable version.
• activate_automation: starts an automation (a workflow with an app trigger) on the latest or a given version, or moves a running one to it without missing or repeating events.
• pause_automation, resume_automation, deactivate_automation: stop, restart, or turn off an automation. get_workflow shows its state.
• set_workflow_enabled: turns a workflow off (API calls, workflow tools, and webhook triggers get 403 WORKFLOW_DISABLED) or back on.

The server also offers the resource kovca://guide (how workflows, references, edit operations, and AI nodes work; agents should read it first), node specs at kovca://nodes/{ref}, and a build_workflow prompt.

Drafts and revisions

Each workflow and workspace node has a draft with a revision that increases with every saved change. Edits and publishes pass the revision they are based on as base_revision. If the draft changed in the meantime (in the Studio, or by another agent), the call fails with REVISION_CONFLICT and the current revision, and nothing changes. Published versions never change.

Workflows as tools

You can give a published workflow its own MCP tool: open the workflow in the Studio, choose API, then MCP tool, and turn on Expose as an MCP tool. The tool is named wf_<name>, takes the workflow's input as its arguments, and runs the latest published version, so an agent with any key can call it directly. Up to 50 workflows per workspace are listed, and agents see a new tool the next time they list tools.

What stays in the Studio

Signing in to an app always needs a person (connect_app hands you the link). Agents can't create HTTP connections or see any credentials, share Instant Workflows, archive workflows, or manage keys, webhooks, or billing. When a workflow needs one of these, the tools return its studio_url so a person can finish there.

Limits and billing

• MCP requests are limited to 120 a minute per workspace (429 RATE_LIMITED with Retry-After), separately from your plan's API rate.
• Runs and tests also count toward your plan's API rate and are billed like any run: run_workflow and workflow tools like API calls (shown as MCP in Executions), and tests like Studio tests. Reading and editing are free.
• Kovca records request metadata for MCP calls (tool name, status, latency, key), never their arguments or results.

Tool failures come back as tool results with isError and the same error codes as the API; see Errors and limits.