How MCP works

The Destesi MCP server is the bridge between an AI agent and your Destesi data. The Model Context Protocol is an open standard for connecting language-model clients to external tools; the Destesi server speaks it and translates each tool call into authenticated Destesi API requests on your behalf.

The mental model

Think of the server as a thin, secure translator:

• Your agent (Claude Code, Claude Desktop, Cursor, or any MCP client) discovers a set of tools and calls them with structured arguments.
• The MCP server receives each call, attaches your identity, and forwards it to the product that owns the operation.
• The product does the real work — provisioning a copy-on-write branch, listing Drive files, creating a Commerce order — and returns structured results the agent can reason about.

The server holds no credential of its own beyond the token you gave it, and it makes no authorization decision. It forwards your token verbatim; each product decides what that token is allowed to do. That is why the surface an agent sees is exactly the surface you already have.

Two servers, deliberately different

Destesi runs two MCP servers, and knowing which one you are talking to explains most surprises.

The hosted endpoint

This is what dst mcp wires up: a /mcp path served by the Destesi API over Streamable HTTP. You don’t operate anything, and every request authenticates with its own bearer token, so one running server can serve many callers, each scoped to their own identity.

Because it lives inside the Destesi API, it exposes only what that API owns directly:

• Snap branching, plus a query tool that runs SQL against a ready branch — the one tool the self-run binary does not have.
• Preview environments — six tools covering create, list, status, events, redeploy, and delete.
• Connect actions — one tool per action in Connect’s catalog.

It does not expose Drive, Deploy, ImageGen, Commerce, TTS, Chat, Studio, or Design tools. Those products are peers with their own APIs; the hosted endpoint does not proxy them.

The self-run binary

This is the mcp binary you run yourself. It talks to each product over the network as a normal API client, which is why it can cover the whole suite — twelve tool families, roughly 75 first-party tools, plus one tool per Connect action.

Run it over stdio and it is a single-user subprocess authenticating every call with one token from its environment. Run it with --http and it serves SSE, authenticating each request from its own Authorization header.

Note

The self-run binary’s Preview family has four tools rather than the hosted endpoint’s six, and its Snap family adds fixtures (branch_promote, branch_restore, fixture_list, fixture_show), branch_lineage, and workspace_list that the hosted endpoint does not carry. Check the reference rather than assuming parity.

Fail-soft tool families

In the self-run binary, Snap, Review, and Preview are always registered. Every other family is gated on that product’s base URL environment variable — DRIVE_API_URL, DEPLOY_API_URL, COMMERCE_API_URL, and so on.

If a variable is unset, the server logs a line saying that family is disabled and carries on. Nothing fails to start, and no other family is affected. This is deliberate: an agent that can reach Drive but not Commerce is far more useful than an agent that refuses to boot because you haven’t configured Commerce.

The same principle governs Connect. The server fetches Connect’s action catalog once at boot and registers one tool per action. Two consequences follow:

• If the catalog is unreachable at boot, the server still starts and registers zero Connect tools.
• If Connect’s catalog changes — a new provider, a new action — you must restart the MCP server to pick it up.

Two workspace conventions

Every operation runs inside a workspace, and you always pass it explicitly as a tool argument. Which argument depends on the family, and this trips people up more than anything else:

Argument	Value	Used by
workspace	Your workspace slug	Connect action tools and the product families (Drive, Deploy, ImageGen, Commerce, TTS, Chat, Studio, Design)
workspace_id	The identity workspace id (ws_…)	Snap, Review, and Preview tools in the self-run binary
identity_workspace_id	The same ws_… id	Snap and Preview tools on the hosted endpoint

The split is historical: the product families authenticate with a workspace header that carries a slug, while Snap and Preview address the workspace by id in the request itself. On the self-run binary, workspace_list returns both, so an agent can discover them. A few Studio tools require both workspace and workspace_id at once.

Copy-on-write, by design

The Snap tools drive Snap, Destesi’s branching engine. A clone or fork produces a fully isolated Postgres endpoint backed by copy-on-write: nothing is duplicated until something changes, so branches are effectively instant, and the source database is never written to. That makes those tools safe to hand to an autonomous agent — it can run migrations, mutate rows, and experiment against a branch without any risk to production.

That safety property belongs to Snap, not to MCP. Other families act on real data: commerce_create_payment_link mints a chargeable payment reference, deploy_apply spends real cloud money, design_restore_version overwrites a sandbox. Read the tool’s description before you let an agent run it unattended.

The trust model

There is no consent gate inside the MCP server. Tools carry readOnly and destructive annotations, and a well-behaved MCP client surfaces those to you before running a tool — but the server does not enforce them and cannot. Enforcement is entirely up to your client.

So the honest summary is: one token grants your agent the entire registered surface. Choose a client that prompts before writes, keep the token where you would keep a password, and revoke it from your account the moment a machine holding it is out of your control.

How it fits the suite

Destesi is a suite of peer products unified by one login and one workspace. You sign in once at account.destesi.io and a single session follows you across every product.

• MCP is the agent-facing surface for the suite. It introduces no data of its own — every tool maps to an operation a product already exposes over its API.
• Authentication is shared. The identity PAT the server uses is the same token the CLI stores at dst login.
• Everything is workspace-scoped. Like every product in the suite, access is governed by your workspace membership.

ReferenceBoth tool catalogs, transports, env vars, and every tool's parameters.

Snap conceptsRemotes, branches, checkpoints, and fixtures explained.

WorkspacesThe unit of collaboration and data isolation.

CLI & authHow dst login and personal access tokens work.