Skip to main content

Getting started

This guide walks through installing, building, and verifying the Ductape MCP server.

Prerequisites​

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

For payload and snippet generation tools, you also need:

  • workspace_id
  • user_id
  • public_key (workspace public key, sent as x-access-key to the payload API)

Install​

From the repository root:

cd platform/mcp-server
npm install

This installs:

  • @modelcontextprotocol/sdk (v1, recommended)
  • @modelcontextprotocol/server (v2 alpha fallback)
  • zod for input validation

Build​

npm run build

This compiles TypeScript to dist/index.js, which is the entry point MCP clients invoke.

Run manually​

Production (compiled):

npm run build && npm start
# equivalent to: node dist/index.js

Development (tsx, no build step):

npm run dev
# equivalent to: tsx src/index.ts

When started, the server waits on stdio for MCP messages. It does not open an HTTP port. You will not see interactive output — that is expected. The server is meant to be spawned by an MCP client.

Verify in Cursor​

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

  • ductape_execute
  • ductape_generate_payload
  • ductape_generate_snippet

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

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

Global install (optional)​

You can link the binary globally after building:

npm link

Then reference ductape-mcp in MCP client config instead of an absolute path to dist/index.js.

Troubleshooting​

IssueFix
Failed to load MCP SDKRun npm install in mcp-server/. Ensure @modelcontextprotocol/sdk is present.
Server starts but tools don't appearRestart the MCP client after config changes. Check that args[0] is an absolute path.
Not authenticated on executePass publishable_key in every ductape_execute invocation.
Proxy validation errorCheck Modules & methods — method names are case-sensitive and dot-notation for nested methods (e.g. environments.create).
Payload generation 401/403Verify public_key, workspace_id, and user_id match your workspace.

Next steps​