Tools reference

The Ductape MCP server exposes runtime, schema, documentation, CLI, Events-discovery, migration, and portable-function setup tools. Responses are JSON text in MCP content blocks. Errors return isError: true with a message string.

`ductape_features_validate_project`

Run this read-only tool before every code-first Feature synchronization. It parses TypeScript and JavaScript Feature definitions under ductape/features/ and reports file, line, column, Feature tag, diagnostic code, and remediation guidance.

{
  "project_dir": "/absolute/path/to/project"
}

It rejects native branches and loops, array control-flow helpers, host-bound time/random/environment access, uninspectable dynamic definitions, and legacy recording options without an explicit legacy mode. A failed result means the agent must stop; features sync must not be called. The CLI repeats the same validation before starting application registration code.

ductape_features_validate_project({ project_dir })
  -> fix every diagnostic
  -> ductape_features_validate_project({ project_dir })
  -> ductape_cli({ command: "features sync", project_dir })

`ductape_function_setup`

Use this whenever a Feature calls application-owned code through ctx.functions. It returns the well-known HTTPS URLs, framework-specific raw-body adapter requirements, HMAC headers, validation checklist, and fail-closed conditions.

{
  "framework": "nestjs",
  "base_url": "https://api.example.com",
  "namespace": "statecraft-auth",
  "version": "1",
  "operations": ["register", "login"]
}

The MCP agent should register local handlers and attempt secure remote exposure in application code. It must not claim remote availability until the route is reachable and rejects an invalid signature. See Portable application functions.

`ductape_execute`

Execute any allowed Ductape SDK operation via the backend proxy at POST /proxy/v1/sdk-proxy/execute.

Arguments

Argument	Type	Required	Description
`publishable_key`	string	No*	Workspace publishable key. Omit if `DUCTAPE_PUBLISHABLE_KEY` is set in the server env config.
`module`	enum	Yes	SDK module name (see Modules & methods)
`method`	string	Yes	Method name; use dot notation for nested methods (e.g. `schema.create`, `messages.query`)
`params`	array	No	Positional arguments matching the SDK signature. Defaults to `[]`.

* Required if DUCTAPE_PUBLISHABLE_KEY is not set in the server environment.

Response

Returns the SDK method result as formatted JSON. On failure, returns Error: <message>.

Examples

Fetch a product:

{
  "module": "product",
  "method": "fetch",
  "params": ["ductape:my-product"]
}

Query a database:

{
  "module": "databases",
  "method": "query",
  "params": [{
    "product": "ductape:my-product",
    "env": "prd",
    "database": "main-db",
    "entity": "users",
    "where": { "status": { "$eq": "active" } },
    "limit": 10
  }]
}

Run an app action:

{
  "module": "actions",
  "method": "run",
  "params": [{
    "product": "ductape:my-product",
    "env": "prd",
    "app": "stripe",
    "action": "create-customer",
    "input": {
      "body:email": "user@example.com",
      "body:name": "Jane Doe"
    }
  }]
}

Vector similarity search:

{
  "module": "vector",
  "method": "findSimilar",
  "params": [{
    "product": "ductape:my-product",
    "env": "prd",
    "vector": "embeddings-index",
    "values": [0.1, 0.2, 0.3],
    "topK": 5
  }]
}

Nested method — list product environments:

{
  "module": "product",
  "method": "environments.list",
  "params": ["ductape:my-product"]
}

Parameter order

params is a JSON array of positional arguments in the same order as the TypeScript SDK. For example, databases.update expects:

"params": [{
  "product": "...",
  "env": "...",
  "database": "...",
  "entity": "...",
  "data": { "name": "Updated" },
  "where": { "id": { "$eq": "123" } }
}]

See Method reference for every signature.

`ductape_generate_payload`

Generate canonical executable payload templates from POST /integrations/v1/payloads/generate. Use this when an agent needs structured payload context before writing SDK code.

Arguments

Argument	Type	Required	Description
`publishable_key`	string	No*	Workspace publishable key. Omit if `DUCTAPE_PUBLISHABLE_KEY` is set in the server env config.
`product_tag`	string	Yes	Product tag (e.g. `ductape:my-product`)
`env_slug`	string	Yes	Environment slug (`prd`, `stg`, etc.)
`operation_family`	string	Yes	Executable family (see Code generation)
`method`	string	Yes	Execution method (`run`, `dispatch`, `query`, etc.)
`targets`	object	No	Component targeting (database tag, action tag, etc.)
`schema_mode`	enum	No	`strict` or `best_effort` (default: `best_effort`)
`include_session`	boolean	No	Include session tags/context (default: `true`)
`include_cache`	boolean	No	Include cache tags/context (default: `true`)
`input_hint`	object	No	Optional schema/input hint for payload generation

Response

{
  "payload": { /* canonical executable payload template */ },
  "meta": { /* schema context, validation info, warnings, inferred tags */ }
}

Example

{
  "product_tag": "ductape:my-product",
  "env_slug": "prd",
  "operation_family": "database",
  "method": "query",
  "targets": { "database": "main-db" },
  "input_hint": { "entity": "orders", "limit": 10 }
}

`ductape_generate_snippet`

Builds on payload generation and returns both the backend payload response and a ready-to-copy SDK code snippet.

Arguments

Same as ductape_generate_payload, plus:

Argument	Type	Required	Description
`language`	enum	No	`typescript` (default) or `python`

Response

{
  "payload": {
    "payload": { /* template */ },
    "meta": { /* metadata */ }
  },
  "snippet": "// TypeScript or Python source code string"
}

Example

{
  "product_tag": "ductape:my-product",
  "env_slug": "prd",
  "operation_family": "action",
  "method": "run",
  "targets": { "app": "stripe", "action": "create-customer" },
  "language": "typescript"
}

Supported snippet operations

Not every SDK method has snippet support. The server validates against an allowlist before generation. See Code generation — Supported snippet operations.

`ductape_cli`

Run a Ductape CLI command for administrative operations. The CLI uses the user's local logged-in session (ductape login) — no key required.

If the CLI is not installed, the tool returns install instructions automatically:

The Ductape CLI is not installed or not in PATH.

Install it with:
  npm install --global @ductape/cli

Then log in:
  ductape login

When to use this tool

Use ductape_cli for any operation that creates or modifies platform configuration, and for syncing declarative resource configs or running database migrations. These require an access key and will fail with Authentication failed if attempted via ductape_execute.

Product and resource management:

Operation	CLI command
List products	`products list`
Create a product	`products create --name "My Product" --tag my-product`
Compact product inventory	`products components list --product-tag my-product --json`
Inspect one component type	`products components get --product-tag my-product --type healthchecks --json`
List apps	`apps list`
Create an app	`apps create -f app.json`
Import app from Postman v2.1	`apps import collection.json -t postman`
Import app from OpenAPI 3.0	`apps import openapi.yaml -t openapi`
Update existing app from file	`apps import v2.json -t postman --app-tag my-workspace:stripe --update`
List resources	`resources storage list`
Create a resource	`resources database create -f db.json`
Manage health checks	`resources health list` / `resources health create -f healthcheck.json`
Link project to product	`link --product my-product --env dev`
List cloud connections	`cloud connections list`
List cloud resources	`cloud resources list --connection <tag>`
Provision a cloud resource	`cloud resources provision -f provision.json`
Provision with a specific tier	`cloud resources provision -f provision.json --tier db.t3.micro`
List all available tiers	`cloud tiers list`
List tiers for a provider	`cloud tiers list --provider gcp`
List tiers by resource type	`cloud tiers list --provider aws --type database --db-type postgresql`
List secrets	`secrets list`
List workspace info	`whoami`
Switch API profile	`profiles list`, `profiles use cloud`

Administrative configuration

Use products environments for product environments and resources quota, resources fallback, resources jobs, or resources health for those administrative resources. App actions and auths remain Workbench-managed. Features are defined in application code and registered at runtime.

Declarative sync — ductape apply:

Sync sessions, notifications, and event brokers declared as JSON files in ductape/ to your product. Requires a linked project.

Operation	CLI command
Sync all (sessions + notifications + events)	`apply`
Sync sessions only	`apply sessions`
Sync notifications only	`apply notifications`
Sync event brokers only	`apply events`
Preview without making changes	`apply --dry-run`

Database schema and migrations — ductape db:

Manage database schema evolution with migration files generated from ductape/database/schema.json. See CLI: Database runtime & migrations.

Operation	CLI command
Generate migration files from schema.json	`db schema generate`
Include drop operations for removed fields	`db schema generate --destructive`
Apply all pending migrations	`db migrate`
Apply to a specific environment	`db migrate --env prd`
Preview without applying	`db migrate --dry-run`
Show applied vs pending migrations	`db migrate status`
Machine-readable status	`db migrate status --json`
Roll back the last migration	`db migrate rollback`
Roll back the last N migrations	`db migrate rollback -n 3`

Arguments

Argument	Type	Required	Description
`command`	string	Yes	The CLI command to run, without the leading `ductape` word.

Example

{
  "command": "product create --name \"Payments Service\" --tag payments-service"
}

Tool selection guide

The key split: ductape_cli for anything that creates or modifies configuration. ductape_execute for anything that runs or reads at runtime.

Goal	Tool
Create or update a product or app	`ductape_cli` (`products create/update`, `apps create/update`)
Create or update resources (DB, storage, graph, vector, cache…)	`ductape_cli` (`resources <type> create/update`)
Manage cloud connections and cloud-linked resources	`ductape_cli` (`cloud connections`, `cloud resources`)
Browse available tiers before provisioning	`ductape_cli` (`cloud tiers list --provider <p> --type <rt>`)
Manage workspace secrets	`ductape_cli` (`secrets`)
Link project folder to a product	`ductape_cli` (`link`)
Sync sessions, notifications, or event brokers from declaration files	`ductape_cli` (`apply`)
Generate or apply database migration files	`ductape_cli` (`db schema generate`, `db migrate`)
Check migration status or roll back	`ductape_cli` (`db migrate status`, `db migrate rollback`)
Configure product environments	`ductape_cli` (`products environments ...`)
Configure quotas, fallbacks, jobs, or health checks	`ductape_cli` (`resources <type> ...`)
Configure app actions or auths	Workbench UI
Define features	Application code (`features.define`)
Validate Feature source before sync	`ductape_features_validate_project`
Persist validated Feature definitions	`ductape_cli` (`features sync`)
Run a feature, action, query, upload, dispatch	`ductape_execute`
Get payload shape before a runtime call	`ductape_generate_payload`
Generate copy-paste SDK code for an engineer	`ductape_generate_snippet`

Error handling

All tools catch exceptions and return text content with isError: true. Common errors:

Error	Cause
`Not authenticated...`	`DUCTAPE_PUBLISHABLE_KEY` not set in server env and `publishable_key` not passed on the tool call
`Proxy request failed: 4xx`	Invalid module/method or params rejected by proxy
`Unsupported snippet operation "family.method"`	Snippet tool called with unsupported operation family/method pair
`Payload generation request failed`	Invalid workspace credentials or backend validation error

ductape_features_validate_project​

ductape_function_setup​

ductape_execute​

Arguments​

Response​

Examples​

Parameter order​

ductape_generate_payload​

Arguments​

Response​

Example​

ductape_generate_snippet​

Arguments​

Response​

Example​

Supported snippet operations​

ductape_cli​

When to use this tool​

Arguments​

Example​

Tool selection guide​

Error handling​

`ductape_features_validate_project`

`ductape_function_setup`

`ductape_execute`

Arguments

Response

Examples

Parameter order

`ductape_generate_payload`

Arguments

Response

Example

`ductape_generate_snippet`

Arguments

Response

Example

Supported snippet operations

`ductape_cli`

When to use this tool

Arguments

Example

Tool selection guide

Error handling