Skip to main content

Getting started

This guide walks through installing and connecting the Ductape MCP server to your AI client.

Prerequisites​

  • Node.js 18+
  • A Ductape account with a workspace Publishable Key (from Workbench → workspace settings)
  • Network access to https://api.ductape.app

Install​

Install the MCP server globally:

npm install -g @ductape/mcp

This makes the ductape-mcp binary available in your terminal. Alternatively, you can skip the install and use npx directly in your MCP client configuration (see below).

Verify​

After installing, confirm the binary is available and check the version:

ductape-mcp --version

The server communicates over stdio and is meant to be spawned by an MCP client. Run it directly only to verify the binary works — --version and --help exit cleanly; any other invocation will hang waiting for MCP protocol input.

Connect to your MCP client​

Configure your client to spawn the server. See Configuration for full instructions.

Quick example (Cursor):

{
  "mcpServers": {
    "ductape": {
      "command": "npx",
      "args": ["-y", "@ductape/mcp"],
      "env": {
        "DUCTAPE_PUBLISHABLE_KEY": "your-publishable-key-here",
        "DUCTAPE_WORKSPACE": "your-workspace-id-here"
      }
    }
  }
}

Both values are in Workbench → Tokens → Publishable key. DUCTAPE_PUBLISHABLE_KEY authenticates runtime calls automatically. DUCTAPE_WORKSPACE scopes all CLI operations to the right workspace and eliminates workspace-resolution round trips.

Verify in Cursor​

After configuring Cursor, open the MCP panel and confirm ductape appears with four tools:

  • ductape_execute
  • ductape_generate_payload
  • ductape_generate_snippet
  • ductape_cli

Ask the agent to list available MCP tools, or invoke a simple read-only call:

{
  "module": "product",
  "method": "fetch",
  "params": ["your-product-tag"]
}

If DUCTAPE_PUBLISHABLE_KEY is set in the server env config, no publishable_key field is needed. You can still pass it explicitly to override the env var.

Troubleshooting​

IssueFix
ductape-mcp: command not foundRun npm install -g @ductape/mcp and ensure your global node_modules/.bin is in $PATH.
Server starts but tools don't appearRestart the MCP client after config changes.
Not authenticated on executeSet DUCTAPE_PUBLISHABLE_KEY in the server env config, or pass publishable_key explicitly on the tool call.
Proxy validation errorCheck Modules & methods — method names are case-sensitive and dot-notation for nested methods (e.g. environments.create).
Payload generation 401/403Verify publishable_key is correct and belongs to the target workspace.

Next steps​