Skip to main content
The Kubiya SDK includes a built-in Model Context Protocol (MCP) server that allows you to expose your workflows as tools to AI assistants like Claude Desktop, Cursor, and other MCP-compliant clients.

​
Overview

The MCP Server acts as a bridge between your local development environment and AI assistants. By running the server, you give AI assistants the ability to:
  1. Discover your local workflows and tools
  2. Compile DSL code into executable workflows
  3. Execute workflows directly from the chat interface
  4. Access documentation and templates

​
Installation

To use the MCP server features, install the SDK with the mcp extra: 
pip install "kubiya-sdk[mcp]"

​
Running the Server

You can start the MCP server using the CLI: 
kubiya mcp server
This will start the server using standard input/output (stdio) transport, which is the standard for local MCP integrations.

​
Configuration

The server can be configured using environment variables or CLI flags:
VariableFlagDescription
KUBIYA_API_KEY--api-keyYour Kubiya Platform API Key
KUBIYA_BASE_URL--base-urlAPI Base URL (default: https://api.kubiya.ai)

​
Connecting to Clients

​
Claude Desktop

To use Kubiya with Claude Desktop, add the following configuration to your claude_desktop_config.json: 
{
  "mcpServers": {
    "kubiya": {
      "command": "kubiya",
      "args": ["mcp", "server"],
      "env": {
        "KUBIYA_API_KEY": "your-api-key-here"
      }
    }
  }
}

​
Cursor

To use Kubiya with Cursor:
  1. Open Cursor Settings > Features > MCP
  2. Click Add New MCP Server
  3. Enter the following details:
    • Name: Kubiya
    • Type: stdio
    • Command: kubiya mcp server
    • Environment Variables: Add KUBIYA_API_KEY=your-key

​
Available Tools

Once connected, the following tools will be available to the AI assistant:

​
compile_workflow

Validates and compiles Python DSL code into a JSON workflow definition. This is useful for checking syntax and structure before execution.

​
execute_workflow

Executes a workflow on the Kubiya platform. Accepts either a compiled JSON definition or raw DSL code.

​
get_workflow_runners

Lists available runners in your Kubiya organization.

​
get_integrations

Lists available integrations (AWS, Slack, etc.) that can be used in workflows.

​
get_workflow_secrets

Lists available secrets that can be injected into workflows.

​
Secrets & the compile_workflow flow

The MCP compile_workflow tool performs an analysis of DSL code to detect references to secrets (for example, placeholders like {{secret:NAME}} used in environment variables or step configuration). The tool’s behavior around secrets is:
  • If missing secrets are detected and no provide_missing_secrets value is provided, compile_workflow will add parameter placeholders to the generated manifest. These parameters are marked as secret and required; the tool will also add environment mappings so runners can receive secret values at execution time.
  • If you supply provide_missing_secrets (either a JSON string or a dictionary) to compile_workflow, the tool will inject those values into the workflow manifest’s env mapping for immediate validation and compilation.
provide_missing_secrets usage examples (accepted as a dict or JSON string): 
# As a dict
compile_workflow(dsl_code=dsl, provide_missing_secrets={"AWS_ACCESS_KEY_ID": "AKIA...", "AWS_SECRET_ACCESS_KEY": "..."})

# As a JSON string
compile_workflow(dsl_code=dsl, provide_missing_secrets='{"AWS_ACCESS_KEY_ID": "AKIA..."}')
Typical compile -> execute secrets flow:
  1. AI or developer writes DSL referencing secrets (e.g. wf.env(AWS_KEY="{{secret:AWS_ACCESS_KEY_ID}}")).
  2. compile_workflow validates the DSL and either prompts for missing secrets or injects provided secret values.
  3. If missing secrets remain, compile_workflow will add secret parameters to the manifest; the agent or caller must provide them at execution time via execute_workflow(..., params=...) or via runner environment configuration.
You can also list available secrets with the get_workflow_secrets tool and use that information to decide which secrets to provide to compile_workflow or execute_workflow.

​
Example Usage

User: “Create a workflow that lists all S3 buckets in us-east-1” Claude/Cursor:
  1. Uses get_integrations to check for AWS integration.
  2. Writes Python DSL code for the workflow.
  3. Uses compile_workflow to validate the code.
  4. Uses execute_workflow to run it.
  5. Returns the execution results to you.