MCP tools

One tool per programmatic operation a tenant key can reach. The read-only column is the tool's own readOnlyHint annotation, which a client may act on.

A tool takes one flat object. The server routes each field to the part of the request the contract puts it in — params, query or body — so a caller never has to know the shape of the URL. The envelope's own fields are below, and are not listed here.

Every tool takes a dryRun beyond its own arguments. Validate this call and report the request that WOULD be sent, without sending it. No state changes and nothing is spent.

A refusal comes back carrying a retry field — what to do next, as a verb — beside the code and the guidance. Branch on retry: it is the same closed set of refusals the command surface answers with, read for action rather than for cause, and it draws a distinction an exit code cannot. Where the binary has one integer for every estate fault, this tells an upstream credential an operator must repair apart from a timeout worth retrying.

Each code carries the same meaning it has on the wire, and the full table — every refusal a customer call can meet, with its HTTP status and the binary's exit code beside it — sits on the scripting page.

Where the credential comes from is a property of the transport, not of the server. The table below is the environment of the stdio server in the server package, which an operator starts by hand and which is not shipped to customers: it reads these three variables once at startup and takes no position on where the value should be held. descant mcp, the stdio server a customer runs, reads two of them: the key, after the one descant login stored, and DESCANT_API_BASE_URL, which it defaults to https://app.descant.run when unset. It finds its own credential and serves the customer catalogue. Connect an agent covers that path.

export DESCANT_API_BASE_URL=https://app.descant.run
export DESCANT_API_KEY=dsc_…

Over HTTP, none of these is read. The caller presents its own bearer on the request and the server builds itself around that one credential for that one call, so nothing is held between calls and there is no environment to set. The origin is fixed by whoever mounts the handler rather than by a variable, and the audience is a constant there — customer — not a setting, so that a mount cannot serve the operator surface by passing a different string.

The server speaks two transports, and the tool surface above is identical on both.

stdio — a server process on your own machine, finding its own credential and speaking JSON-RPC over standard input and output. This is the shape an MCP client launches and supervises itself. It presents the key stored on the machine, else an exported one; with neither, the first tool call that needs a key opens your browser to sign you in, from cli-v0.1.8 onwards. The descant binary serves this same catalogue over stdio as descant mcp, from cli-v0.1.1 onwards — connect an agent carries the configuration block.

For operators only, descant mcp --admin serves the operator tools beside the ones above. They are listed from the moment the server starts, and the first operator tool call made with no operator credential on the machine opens the same browser sign-in descant login --admin runs, for an allowlisted admin to approve. What it stores is a short-lived credential, in a named slot of its own in your credential store — never a long-lived fleet token. Without the flag nothing changes: a tenant key never sees an operator tool.

HTTP — a request in, a response out, with the caller presenting its own key rather than the server holding one. It serves the customer audience and nothing else, and it copies exactly two headers from your request onto the call it makes — x-forwarded-for and x-real-ip — so rate limiting keys on the caller you already are, not on one shared bucket for everyone.

To drive Descant from a program today, the shipped surface is the descant binary: install it in one line and read scripting and agents for its JSON output, exit codes and refusals. Every tool above is a command there.

A remote MCP client that supports OAuth sign-in needs only the endpoint's address — no key to paste:

https://app.descant.run/api/v1/mcp

Discovery is automatic. The client's first call carries no key and is answered 401 with a WWW-Authenticate header that points at the endpoint's sign-in metadata. From there the client finds where to register and where to send you, registers itself, and opens your browser at the Descant sign-in you already use. Once signed in you see which application is asking and where the answer will be sent, choose the organization and the permissions it gets, and approve. Only an organization owner can approve.

The client then receives a short-lived key carrying exactly the permissions you approved, and calls the tools above with it. The key appears in your API key list, so you can see it and revoke it like any other.

A key you mint yourself still works. A client configured to send authorization: Bearer <your key> on every request is admitted exactly as before, and never sees the sign-in. Browser sign-in adds a way in; it removes none. Connect an agent covers that configuration.