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)
  • An authenticated Ductape CLI session for administrative tools
  • Network access to https://api.ductape.app

Install​

Install the MCP server globally:

npm install -g @ductape/mcp
npm install -g @ductape/cli
ductape login --browser google   # or: ductape login --browser github
ductape whoami                   # must show the intended workspace

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 MCP runtime calls; it does not authenticate the CLI and it is not the server SDK Access Key. DUCTAPE_WORKSPACE scopes CLI operations, but administrative MCP tools still use the separate local session created by ductape login. Verify that session with ductape whoami.

Verify in Cursor​

After configuring Cursor, open the MCP panel and confirm ductape appears. MCP 0.3.3 exposes 19 tools, including ductape_doctor, ductape_schema, ductape_docs, runtime execution, project validation/setup, migration, and CLI tools. The tool set can grow between releases, so let the client enumerate it rather than validating against a fixed four-tool list.

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

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

Run ductape_doctor first. It checks package compatibility, CLI authentication, workspace scope, and project linkage without exposing credentials.

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.
Administrative tool says CLI is not authenticatedWebsite sign-in is separate. Run ductape login --browser google in a terminal, then ductape whoami, and restart/retry the MCP client.
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​