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 full-suite server reads, and every tool it exposes.

If you are unsure which one you have, dst mcp wires you to the hosted endpoint. A client pointed at https://mcp.destesi.io/sse, or a command entry in your mcpServers config pointing at an mcp binary, is the full-suite server.

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, Space, Lens, or Review tools, and it does not expose Snap’s fixture, lineage, or workspace_list tools. For those, use the full-suite server below.

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 full-suite server

The mcp binary. It reaches every product over the network, which is why it carries the full suite surface: every family in Tool families plus one tool per Connect action.

Destesi-hosted

Destesi runs it at https://mcp.destesi.io/sse over the SSE transport, with every product family switched on. Nothing to operate:

claude mcp add -t sse -s user destesi https://mcp.destesi.io/sse \
  -H "Authorization: Bearer idn_pat_…"

Any MCP client that speaks SSE can connect: open the stream at /sse and post messages back to the /message?sessionId=… endpoint it hands you. Requests without a bearer token are rejected with 401.

Transports

Run the binary yourself when you want it closer to your machine, or pointed at a different Destesi deployment.

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
SPACE_API_URL	No	—	Space API base URL — registers the space_* tools
LENS_API_URL	No	—	Lens API base URL — registers the lens_* tools
RELAY_API_URL	No	—	Relay API base URL — registers the relay_* 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

17 families, 400 first-party tools, plus one tool per Connect action. Each family’s page lists every tool it registers with the description the server sends in tools/list.

Family	Switched on by	Tools
Snap	always	18
Workspace	always	11
Review	always	1
Preview	always	4
Connect	CONNECT_API_URL	13, plus one per catalog action
Drive	DRIVE_API_URL	14
Deploy	DEPLOY_API_URL	7
ImageGen	IMAGEGEN_API_URL	3
Commerce	COMMERCE_API_URL	159
TTS	TTS_API_URL	8
Chat	CHAT_API_URL	16
Studio	STUDIO_API_URL	29
Design	DESIGN_API_URL	25
Space	SPACE_API_URL	29
Lens	LENS_API_URL	25
Relay	RELAY_API_URL	35
Inventory	INVENTORY_API_URL	3

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, Space, Lens) — full-suite server
workspace_id	Identity workspace id (ws_…)	Snap, Review, and Preview tools — full-suite server
identity_workspace_id	The same ws_… id	Snap and Preview tools — hosted endpoint

On the full-suite server, 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 full-suite server’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 (full-suite server; 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.