MCP reference

Destesi runs two MCP servers with different tool registries. This page documents both: how to reach each one, how to authenticate, the environment the self-run binary reads, and every tool it exposes.

If you are unsure which one you have, dst mcp wires you to the hosted endpoint. A command entry in your client’s mcpServers config pointing at an mcp binary is the self-run binary.

The hosted endpoint

Served by the Destesi API at the /mcp path (for example https://api.destesi.io/mcp) over the Streamable HTTP transport. You don’t run or configure anything — dst mcp registers it with Claude Code for you, and any MCP client that speaks Streamable HTTP can connect.

Authentication. Every request carries its own Authorization: Bearer <token> header. A request without one is rejected with 401, which is what makes a client show the server as “not connected” until you authenticate. Use an identity PAT (idn_pat_…) — the same token dst login stores.

Tools

Family	Tools
Snap	remote_add, remote_list, remote_show, remote_remove, clone, fork, branch_list, status, remote_url, branch_delete, wait, query, log
Preview	preview_create, preview_list, preview_status, preview_events, preview_redeploy, preview_delete
Connect	One connect_{provider}_{action} tool per action in Connect’s catalog

That is the whole surface. The hosted endpoint does not expose Drive, Deploy, ImageGen, Commerce, TTS, Chat, Studio, Design, or Review tools, and it does not expose Snap’s fixture, lineage, or workspace_list tools. For those, run the binary.

The workspace argument is named differently here

Hosted Snap and Preview tools take identity_workspace_id, not workspace_id. The value is the same ws_… identifier; only the argument name differs. See workspace arguments below.

query — SQL against a branch

Unique to the hosted endpoint. Runs a SQL statement against a ready branch’s Postgres endpoint and returns the results as JSON.

Parameter	Type	Required	Description
snap_id	string	yes	Branch/snap ID to query (must be ready)
sql	string	yes	SQL statement to execute
max_rows	number	no	Maximum rows to return (default 100, max 1000)
read_only	boolean	no	Run in a read-only transaction (default true)
timeout_seconds	number	no	Query execution timeout (default 30, max 120)

Leaving read_only at its default is the safe posture: the statement runs in a read-only transaction, so an agent cannot write even if it composes a mutating statement. Set it to false only when you intend the agent to run INSERT, UPDATE, DELETE, or DDL.

Preview tools

Tool	Purpose
preview_create	Register a new preview environment. This only creates the record — for tarball-source previews, a tarball must be uploaded before the controller can provision.
preview_list	List previews, optionally filtered by workspace and/or status (pending, building, healthy, failed).
preview_status	Show a preview’s status, including its public URL once ready.
preview_events	List lifecycle events (created, build_started, healthy, failed, deleted) for a preview.
preview_redeploy	Queue a preview for tear-down and rebuild — useful after pushing a new commit.
preview_delete	Delete a preview and tear down all its resources.

The self-run binary

The mcp binary you run yourself. It reaches every product over the network, which is why it carries the full suite surface.

Transports

stdio (default)

For local desktop clients (Claude Desktop, Cursor). The client launches the mcp binary as a subprocess. DESTESI_API_KEY is required — there is no per-request header to authenticate with.

DESTESI_API_URL=https://api.destesi.io \
  DESTESI_API_KEY=idn_pat_… \
  mcp

HTTP/SSE

For hosted or shared use. Pass --http with a listen address; each request authenticates with its own Authorization: Bearer header.

DESTESI_API_URL=https://api.destesi.io \
  mcp --http :8080

A bare port is also accepted (--http 8080 is normalized to :8080). Requests without a bearer token are rejected with 401. Front this transport with an authenticating endpoint — it trusts the presented bearer.

Authentication

The server authenticates as you, using an identity personal access token (PAT) — the same idn_pat_… token dst login stores. It holds no credential of its own.

• stdio: the process-wide DESTESI_API_KEY authorizes every call. It is required; the server refuses to start without it.
• HTTP/SSE: each request is authenticated by its own Authorization: Bearer <token> header, and a per-call client is built from that token. DESTESI_API_KEY acts only as a fallback.

The token is forwarded verbatim to whichever product owns the tool, including Connect action tools — MCP never substitutes a credential of its own, and never makes an authorization decision. What your agent can do is exactly what your token can do.

Use an identity PAT

One identity PAT authorizes the entire surface: Snap branching, workspace_list, Connect actions, and every product family. A product-scoped personal key does not satisfy the workspace_list path — use the identity PAT.

Environment variables

The first three configure the server itself. The rest each switch on one tool family.

Variable	Required	Default	Purpose
DESTESI_API_URL	Yes in --http mode	http://localhost:8080	Destesi API base URL — backs the Snap, Review, and Preview tools
DESTESI_API_KEY	Yes in stdio mode	—	Identity PAT (idn_pat_…); in --http mode a fallback only (per-request bearer preferred)
DESTESI_IDENTITY_API_URL	No	value of DESTESI_API_URL	Identity API base URL for workspace_list
CONNECT_API_URL	No	—	Connect API base URL — registers one tool per catalog action
DRIVE_API_URL	No	—	Drive API base URL — registers the drive_* tools
DEPLOY_API_URL	No	—	Deploy API base URL — registers the deploy_* tools
IMAGEGEN_API_URL	No	—	ImageGen API base URL — registers the imagegen_* tools
COMMERCE_API_URL	No	—	Commerce API base URL — registers the commerce_* tools
TTS_API_URL	No	—	TTS API base URL — registers the tts_* tools
CHAT_API_URL	No	—	Chat API base URL — registers the chat_* tools
STUDIO_API_URL	No	—	Studio API base URL — registers the studio_* tools
DESIGN_API_URL	No	—	Design API base URL — registers the design_* tools

Note

Unset means skipped, not broken. Every product base URL is optional. Leave one unset and the server logs that the family is disabled and starts anyway — Snap, Review, and Preview always register, and no other family is affected. Configure only what you want your agent to reach.

In single-host setups, leaving DESTESI_IDENTITY_API_URL unset is fine — it defaults to DESTESI_API_URL. Set it explicitly when the identity service lives on a different host. In --http mode the server refuses to start if DESTESI_API_URL is left at the localhost default, so a misconfigured deployment fails loudly instead of coming up “healthy” and refusing every call.

Tool families

Twelve families, roughly 75 first-party tools, plus one tool per Connect action.

Family	Switched on by	Tools
Snap	always	remote_add remote_list remote_show remote_remove clone fork branch_list status remote_url branch_delete wait fixture_list fixture_show branch_promote branch_restore branch_lineage log workspace_list
Review	always	review_list_reviews
Preview	always	preview_list preview_get preview_create preview_delete
Connect	CONNECT_API_URL	One connect_{provider}_{action} per catalog action
Drive	DRIVE_API_URL	drive_list_folders drive_list_files drive_get_file drive_get_download_url drive_create_folder
Deploy	DEPLOY_API_URL	deploy_list_deployments deploy_get_deployment deploy_get_readiness deploy_create_deployment deploy_send_message deploy_apply deploy_destroy
ImageGen	IMAGEGEN_API_URL	imagegen_list_engines imagegen_list_gallery imagegen_generate
Commerce	COMMERCE_API_URL	commerce_list_products commerce_get_product commerce_list_categories commerce_list_orders commerce_get_order commerce_list_campaigns commerce_create_product commerce_create_order commerce_create_payment_link commerce_fulfill_order commerce_cancel_order
TTS	TTS_API_URL	tts_list_voices tts_get_voice tts_list_jobs tts_get_job tts_get_job_audio_url tts_synthesize tts_delete_voice
Chat	CHAT_API_URL	chat_list_conversations chat_get_conversation_messages chat_delete_conversation chat_rename_conversation chat_list_models
Studio	STUDIO_API_URL	studio_list_projects studio_get_project studio_create_project studio_delete_project studio_list_runs studio_get_run studio_approve_run
Design	DESIGN_API_URL	design_list_projects design_get_project design_create_project design_list_files design_get_file_content design_list_history design_restore_version

What each product tool does

Drive

Tool	Purpose
drive_list_folders	List folders in a Drive workspace, optionally scoped to a parent folder.
drive_list_files	List files, optionally scoped to a folder.
drive_get_file	Get metadata for one file (name, mime type, size, uploader).
drive_get_download_url	Get a time-limited signed download URL for a file.
drive_create_folder	Create a new folder.

Deploy

Tool	Purpose
deploy_list_deployments	List Deploy deployments in a workspace.
deploy_get_deployment	Get one deployment’s state, repo, region, and live URL.
deploy_get_readiness	Get a deployment’s readiness report — the blockers the advisor found before apply.
deploy_create_deployment	Create a deployment from a GitHub repo and a natural-language prompt. Plans only; no cloud spend until deploy_apply.
deploy_send_message	Send a chat message to an existing deployment (for example “add a database”) to revise its manifest. Never auto-applies.
deploy_apply	Run terraform apply. Spends real cloud money and provisions real infrastructure.
deploy_destroy	Tear down a deployment’s live infrastructure. Irreversible.

Commerce

Tool	Purpose
commerce_list_products	List products in a Commerce workspace.
commerce_get_product	Get one product’s details (price, stock, category, images).
commerce_list_categories	List product categories.
commerce_list_orders	List orders.
commerce_get_order	Get one order’s details (status, totals, buyer, payment, delivery).
commerce_list_campaigns	List ad campaigns.
commerce_create_product	Create a product. Package dimensions and a Drive-hosted image are required for shipping-rate calculation.
commerce_create_order	Create an order for an anonymous buyer, reserving stock per line. Does not charge payment.
commerce_create_payment_link	Mint a real, chargeable payment reference (hosted checkout or bank-transfer instructions) for an order.
commerce_fulfill_order	Mark an order fulfilled. Legal only from paid.
commerce_cancel_order	Cancel an order and release its stock reservations. Paid and fulfilled orders cannot be cancelled this way.

TTS

Tool	Purpose
tts_list_voices	List the voices available to a TTS workspace.
tts_get_voice	Get one voice’s detail.
tts_list_jobs	List synthesis jobs.
tts_get_job	Get one job’s status, text, and duration.
tts_get_job_audio_url	Get a time-limited signed URL for a finished job’s audio file.
tts_synthesize	Synthesize speech from text with a given voice. Queues a job, or waits inline for short text.

Chat, Studio, Design

Tool	Purpose
chat_list_conversations	List Chat conversations in a workspace.
chat_get_conversation_messages	List messages in one conversation.
chat_delete_conversation	Delete a conversation and its message history.
chat_rename_conversation	Rename a conversation.
chat_list_models	List available chat models for a workspace.
studio_list_projects	List Studio content projects.
studio_get_project	Get one project’s details.
studio_create_project	Create a content project from a natural-language prompt.
studio_delete_project	Delete a project.
studio_list_runs	List agent runs for a project.
studio_get_run	Get one run’s state and steps.
studio_approve_run	Approve a run for render and publish.
design_list_projects	List Design (AI app builder) projects.
design_get_project	Get one project’s details.
design_create_project	Create a new project.
design_list_files	List file paths in a project’s sandbox.
design_get_file_content	Get one file’s content from a project’s sandbox.
design_list_history	List a project’s version history.
design_restore_version	Restore a project to a prior version. Overwrites the current sandbox state.

ImageGen & Review

Tool	Purpose
imagegen_list_engines	List image-generation engines available to the workspace.
imagegen_list_gallery	List the workspace’s previously generated images.
imagegen_generate	Generate an image from a text prompt. Synchronous — the response carries the finished image_url. Incurs compute cost per call.
review_list_reviews	List code reviews run by the Destesi review bot for a workspace.

Connect action tools

When CONNECT_API_URL is set, the server fetches Connect’s action catalog at boot and registers one tool per action — over 200 actions across around 40 providers. Each tool is named connect_{provider}_{action} (for example connect_github_create_issue) and takes a wrapped schema:

{
  "workspace": "acme",
  "args": { "owner": "acme", "repo": "site", "title": "hello from my agent" }
}

The args object is the action’s own input schema, straight from Connect’s catalog. Each tool carries the action’s read / write / destructive annotation so a well-behaved client can prompt you before a write.

Two behaviours worth knowing:

• The catalog is read once, at boot. If Connect adds a provider or an action, restart the MCP server to see it.
• An unreachable catalog is not fatal. The server logs it, registers zero Connect tools, and every other family still serves.

Common errors come back as tool results, not transport failures: not_connected means you need to authorize that provider in Connect first, and insufficient_scope means the connection exists but was authorized without the scopes this action needs — reconnect it.

Workspace arguments

Every workspace-scoped tool takes the workspace explicitly. Three argument names are in play, and passing the wrong one is the single most common mistake:

Argument	Value	Where
workspace	Workspace slug (for example acme)	Connect action tools and the product families (Drive, Deploy, ImageGen, Commerce, TTS, Chat, Studio, Design) — self-run binary
workspace_id	Identity workspace id (ws_…)	Snap, Review, and Preview tools — self-run binary
identity_workspace_id	The same ws_… id	Snap and Preview tools — hosted endpoint

On the self-run binary, workspace_list returns both the id and the slug for every workspace you belong to, so an agent can discover whichever it needs.

Studio wants both

studio_list_projects and studio_create_project require both workspace (the slug) and workspace_id (the ws_… id) in the same call. Passing only one returns a missing-argument error.

Snap tool parameters

The parameter tables below use workspace_id, the self-run binary’s name. On the hosted endpoint the same argument is named identity_workspace_id.

Discovery

workspace_list

List the workspaces the authenticated caller is a member of, with each workspace’s id, slug, name, and your role. Use it to find the id and slug other tools need. Takes no parameters. Self-run binary only.

Remotes (data sources)

remote_add

Register a Postgres database or S3 bucket as a remote source (like git remote add).

Parameter	Type	Required	Description
workspace_id	string	yes	Workspace to add the remote to
kind	string	no	postgres (default) or s3
name	string	no	Display name for the remote
dsn	string	no	PostgreSQL connection string (required for postgres)
s3_bucket	string	no	S3 bucket name (required for s3)
s3_region	string	no	S3 region (default: us-east-1)
s3_endpoint	string	no	Custom S3 endpoint for S3-compatible storage
s3_access_key	string	no	S3 access key ID
s3_secret_key	string	no	S3 secret access key

remote_list

List all remotes in a workspace (like git remote -v).

Parameter	Type	Required	Description
workspace_id	string	yes	Workspace to list remotes for

remote_show

Show a remote’s details, status, and sync lag (like git remote show).

Parameter	Type	Required	Description
connector_id	string	yes	Remote/connector ID

remote_remove

Remove a remote from your workspace. If other workspaces share the remote it keeps running for them; it is fully torn down only when the last workspace removes it.

Parameter	Type	Required	Description
connector_id	string	yes	Remote/connector ID to remove

Branches

clone

Clone a remote source into a new isolated branch (like git clone). Creates a full Postgres endpoint backed by copy-on-write and returns a branch ID and operation ID — pass the operation ID to wait to block until ready.

Parameter	Type	Required	Description
workspace_id	string	yes	Workspace to create the branch in
connector_id	string	yes	Remote/connector to clone from
name	string	yes	Branch name (e.g. main, staging)
checkpoint_id	string	no	Pin to a specific checkpoint (point-in-time)
max_lag	number	no	Maximum acceptable sync lag in seconds
overrides	object	no	Per-table column rewrites applied as rows copy from source (see below)

fork

Fork an existing branch into a new isolated branch (like git checkout -b). The new branch starts as a copy-on-write clone of the parent; both are fully isolated afterward.

Parameter	Type	Required	Description
workspace_id	string	yes	Workspace to create the branch in
parent_snap_id	string	yes	Branch to fork from (must be ready)
name	string	yes	New branch name (e.g. feature/auth-fix)
overrides	object	no	Per-table column rewrites applied on first access to each table (see below)

branch_list

List all branches in a workspace with their status and endpoint (like git branch -v).

Parameter	Type	Required	Description
workspace_id	string	yes	Workspace to list branches for

status

Show a branch’s status, endpoint DSN, parent, and metadata (like git status).

Parameter	Type	Required	Description
snap_id	string	yes	Branch/snap ID

The returned status field is one of:

Status	Meaning
pending	The branch was created and is queued for provisioning
provisioning	The endpoint is being created (copy-on-write backend coming up)
ready	The endpoint is live and the DSN is assigned — remote_url will return it
error	Provisioning failed
expired	The branch passed its time-to-live and was retired
deleted	The branch was removed and its resources released

A branch is usable for remote_url, fork, query, and branch_promote only when it is ready; on any other status those tools return an error. See Snap concepts for the full lifecycle.

remote_url

Get the connection string (DSN) for a ready branch (like git remote get-url). Returns an error if the branch is not yet ready.

Parameter	Type	Required	Description
snap_id	string	yes	Branch/snap ID

branch_delete

Delete a branch and release its resources (like git branch -D).

Parameter	Type	Required	Description
snap_id	string	yes	Branch/snap ID to delete

wait

Wait for a branch to finish provisioning. Polls the operation until the branch is ready or fails, then returns the branch details including the endpoint DSN. Use after clone or fork.

Parameter	Type	Required	Description
operation_id	string	yes	Operation ID returned by clone, fork, or branch_restore
timeout_seconds	number	no	Max seconds to wait (default: 120)

Fixtures

A fixture is a named, pinned branch future branches can be forked from — a way to capture a known-good state that survives ad-hoc branch deletion. Self-run binary only.

branch_promote

Pin a ready branch as a named fixture. The source branch is protected from deletion while any fixture references it.

Parameter	Type	Required	Description
snap_id	string	yes	Branch/snap ID to pin (must be ready)
name	string	yes	Fixture name (unique within the environment)
description	string	no	Optional human-readable description

branch_restore

Instantiate a new branch forked from a saved fixture. Returns the new branch ID and an operation ID — pass it to wait.

Parameter	Type	Required	Description
fixture_id	string	yes	Fixture to restore from
name	string	yes	Name for the new branch
max_lag	number	no	Maximum acceptable sync lag in seconds

fixture_list

List saved fixtures in a workspace.

Parameter	Type	Required	Description
workspace_id	string	yes	Workspace to list fixtures for

fixture_show

Show a fixture’s details, including the source branch it pins.

Parameter	Type	Required	Description
fixture_id	string	yes	Fixture ID (prefix fixture_)

History & lineage

log

List available checkpoints (point-in-time snapshots) for a remote — the commit history of your data source (like git log).

Parameter	Type	Required	Description
connector_id	string	yes	Remote/connector ID to list checkpoints for

branch_lineage

Walk a branch’s parent chain and return its lineage from the branch back to its root remote — useful for understanding how a branch was derived. Self-run binary only.

Parameter	Type	Required	Description
snap_id	string	yes	Branch/snap ID to start from
max_depth	number	no	Stop after this many ancestors (default: 20)

Column overrides

Both clone and fork accept an optional overrides object that rewrites specific columns as a branch materializes — for example, masking PII or flipping flags. Each set value is a raw SQL expression evaluated against the source row; where is optional.

{
  "tables": [
    {
      "table": "users",
      "set": { "email": "'me@example.com'", "is_admin": "false" },
      "where": "role = 'customer'"
    }
  ]
}

Example agent workflow

// 1. Discover the workspace (self-run binary; returns id + slug)
workspace_list {}

// 2. Clone a branch from a remote
clone { "workspace_id": "ws_abc", "connector_id": "conn_abc", "name": "agent/run-42" }

// 3. Block until the branch is ready
wait { "operation_id": "op_xyz" }

// 4. Get the DSN and connect
remote_url { "snap_id": "snap_abc" }
// → postgresql://snap-abc.snap.destesi.io:5432/db

// 5. Agent runs queries, mutations, migrations against the branch...

// 6. Clean up
branch_delete { "snap_id": "snap_abc" }

Note the two workspace forms in one session: workspace_id for the Snap tools above, but workspace (the slug) for a product tool such as drive_list_files { "workspace": "acme" }.

Note

The Snap tools mirror the dst snap CLI verbs closely, so any Snap operation an agent runs can also be reproduced by hand with the CLI or the Snap reference. That is not true of the surface as a whole — most of the product and Connect tools have no CLI equivalent and are reachable only through MCP or the product’s own API.