> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoista.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tool catalog

> Tools available through the Hoista MCP server.

Hoista exposes **82 MCP tools** for projects, deploys, provider controls and operation history. Each call goes through the daemon, which checks the client grant and any required approval. Use `tools/list` to inspect the schemas and tools available to your connection.

Expand a tool for its description, or [download the catalog](https://docs.hoista.dev/assets/mcp-catalog.json).

> [accordion] get\_my\_access
>
> **Read-only hint.** Read what this connection may do: its scopes (read, deploy and change, create), the projects and environments it may touch, tools it may never use, and when its access ends. Call this before planning work, instead of finding out by being refused. active\_project is the project of the folder this agent works in (named in its .hoista/project.json, its source folder, or a clone of its repository), or null: tools about one project use it when project\_id is left out.

> [accordion] resolve\_operation
>
> **May change state.** Say whether an unclear change happened at the provider (an operation.unclear refusal names it), after reading the provider to see. Give what you read as evidence; it's kept with the change and shown to the person in Activity. Then an identical change can be made again. Before saying it didn't happen, read twice a few seconds apart: providers can be slow to list something new.

> [accordion] use\_project
>
> **Read-only hint.** Make a project the active project of the folder this agent works in, by writing its id to .hoista/project.json at the repository's root (kept out of git: ids are this computer's own). Later sessions in that folder find it without being told. Only for a coding tool on this computer.

> [accordion] list\_environments
>
> **Read-only hint.** List Hoista's environments: separate spaces for projects, such as default and production. Every project is in one. They are Hoista's own; a provider's environments (such as a preview environment) are separate. Only environments this connection may touch are listed.

> [accordion] move\_project
>
> **May change state.** Move a project into another Hoista environment, such as from default to production. Nothing changes at the provider. Fails when that environment already has a project of the same name.

> [accordion] list\_projects
>
> **Read-only hint.** List every project on every connected provider with its observed status, public URL, resources and last deploy, with cursor pagination. Watched projects (mode watching) run on their provider; Hoista reads them.

> [accordion] get\_attention
>
> **Read-only hint.** Read what needs the person: pending approvals and notices such as failed deploys, failing or idle resources and accounts to reconnect. Follow both cursors to read everything.

> [accordion] get\_database\_operations
>
> **Read-only hint.** Read a page of database operations. Finished starts are counted only within this page, not as a daily or lifetime wake total.

> [accordion] refresh\_resource\_bindings
>
> **May change state.** Refresh the bindings a provider reports into the local map without changing cloud configuration. Disappeared observed edges are retained as missing.

> [accordion] get\_project
>
> **Read-only hint.** Read a project's status, resources (with each resource's provider, status and URL), links, last deploy and usage stats.

> [accordion] list\_provider\_operations
>
> **Read-only hint.** List everything the provider behind a resource (resource\_id) or a connected account (account\_id) can do through Hoista: its full API and, where Hoista has one, its command-line tool (operations named like `supabase db push`, run by Hoista with the token so you never need it or the CLI), grouped by area (deploys, environments, networking, storage and backups, observability, edge, templates, feature flags…). Each entry has its name, risk (read, change, or destroy, which needs the person's approval) and required arguments. Filter with area. Then call describe\_provider\_operation for an operation's full argument schema, and run\_provider\_operation to run it.

> [accordion] describe\_provider\_operation
>
> **Read-only hint.** Read one provider operation's full argument schema. Arguments marked filled\_in (project, environment, service, workspace) are filled from resource\_id or account\_id when you leave them out.

> [accordion] give\_key
>
> **May change state.** Give one service a key to another without anyone handling it, and set it straight into that service's variables: on Resend Hoista makes a key that can only send from the domain (RESEND\_API\_KEY); on Supabase it takes the project's public anon or publishable key (SUPABASE\_ANON\_KEY; pass variable, such as NEXT\_PUBLIC\_SUPABASE\_ANON\_KEY, for a browser app). The key is never returned or kept. Use this instead of asking the person to create or paste a key.

> [accordion] move\_resources
>
> **May change state.** Move resources into another project, from whichever project they are in now: for a resource that landed in the wrong project, such as one Hoista put in a project of its own after a provider operation created it. Nothing changes at the provider and the project keeps its mode. A project left empty with no deploys is removed.

> [accordion] run\_provider\_operation
>
> **May change state.** Run one operation from list\_provider\_operations on a resource (resource\_id) or account (account\_id), with args as an object. When it creates something, pass project\_id so it joins that project; without it, something made on an account becomes a project of its own. Reads return the provider's answer with secrets removed; changes are recorded in Activity; destroy operations return pending with an approval\_id the first time: retry with it once the person allows it in Hoista. Prefer Hoista's dedicated tools (deploy\_folder, set\_secret, get\_logs…) where they exist; use this for everything else. Never put a key's value in args: for variables an operation takes (a pod's env, say), pass env\_file (a .env file's absolute path) and env\_names, and Hoista puts the values in env\_arg itself and keeps them out of the answer.

> [accordion] get\_metrics
>
> **Read-only hint.** Read a resource's numbers over a range (1h, 24h, 7d, 30d) as its provider reports them, for providers whose capabilities include metrics. Most providers answer with charts: each has an id, label, unit (count, milliseconds, percent, bytes, cores, seconds) and lines of \{at, value} points, such as requests by status class, response time, CPU, memory or emails sent; note says what the provider couldn't answer. Railway answers requests and errors by status code, response time p50/p90/p95/p99, CPU and memory with their limits, network and disk, each series \[\{ts, value}], with null for what it doesn't report. Nothing is estimated.

> [accordion] get\_bills
>
> **Read-only hint.** Read what each connected provider has actually billed so far this billing period, one row per connected account: bill (the money billed, with the period) when the provider shares it, plan\_usage where it counts usage but not money, and note saying why when there is neither (no charges yet, the token can't read billing, the provider didn't answer). Hoista never estimates cost, and per-project costs are not available.

> [accordion] get\_provider\_details
>
> **Read-only hint.** Read what the provider reports for a resource right now (for providers that support it): its own deployment history with status, commit and time, its variable names (never values) and its domains. Nothing changes at the provider.

> [accordion] get\_project\_map
>
> **Read-only hint.** Read resource nodes and dependency edges.

> [accordion] create\_project
>
> **May change state.** Create an empty project. With source (a folder or repository), it's for plan\_deploy and deploy, which Hoista builds and sends to a provider it deploys to. Without source, it's a project whose pieces you add at any providers with add\_to\_project: code, databases, buckets, email domains and images, one call each. To have one provider build a repository as a project of its own, use create\_project\_at\_provider. Only for a new project: when the folder already belongs to one (get\_my\_access, active\_project) it's refused unless confirm\_new is true with a reason, which you set only when the person said it's new. After making one, call use\_project so later sessions find it.

> [accordion] create\_project\_at\_provider
>
> **May change state.** Create a new project at a provider, on a connected account: from a GitHub repository (repo) where its capabilities include new\_app, as a new project of its own with one service deploying the repo and a public address; or from a folder on this computer where they include new\_from\_folder, deployed with the provider's own tool (Modal: the folder's Python file that makes a modal.App, deployed under the project's name): give folder for a new project, or project\_id for an empty project you already linked to a folder with create\_project. This is how a first deploy to Modal is made; its modal deploy operation only redeploys an app Hoista already watches. The provider builds it; Hoista watches it like any watched project. Returns the project and its resources. Then call get\_provider\_details for the newest deployment id and wait\_for\_deploy with it. Never adds anything to a project that already has resources: for that, use add\_to\_project.

> [accordion] list\_domains
>
> **Read-only hint.** Read a page of saved hostnames and their last DNS/certificate observations for a project.

> [accordion] check\_domain
>
> **May change state.** Refresh a managed hostname's DNS/certificate state. Requires apps:write; may trigger provider validation. Fly checks never recreate a removed hostname.

> [accordion] delete\_domain
>
> **May change state.** Request approval to detach a hostname and ALL its certificates (including custom Fly certificates), then retry with approval\_id. Leaves DNS records and the project intact. An uncertain provider result requires inspection and a new approval, not replay.

> [accordion] add\_domain
>
> **May change state.** Add a custom hostname to a managed resource; requires apps:create. A missing DNS zone is created only when create\_zone is explicitly true.

> [accordion] plan\_deploy
>
> **May change state.** Inspect a local folder and create a deployment plan. With project\_id, the folder is the project's source folder or one inside it (one app of a monorepo), and the plan uses the project's existing database instead of making another; deploy it with the same project\_id.

> [accordion] get\_plan
>
> **Read-only hint.** Read a saved plan and its revision, including immutable queued snapshots.

> [accordion] edit\_plan
>
> **May change state.** Validate and reprice a saved plan without deploying. Preserve its read revision; stale edits fail and must be reviewed against a fresh read. Queued snapshots cannot be edited.

> [accordion] deploy
>
> **May change state.** Queue a saved deployment plan for a managed project.

> [accordion] cancel\_deploy
>
> **May change state.** Request cancellation at the next safe boundary; in-flight provider writes may finish first.

> [accordion] rollback
>
> **May change state.** Restore a previously successful deployment by id.

> [accordion] list\_repositories
>
> **Read-only hint.** List the GitHub repositories a connected GitHub account (provider github, from get\_my\_access) can reach, newest pushed first: owner/name, default branch, private or not, last push. Use it to find where a project's code lives before pushing to it with git. Listing needs only the token's metadata access; link\_repository also reads the newest commit, so it needs Contents: read on the repository.

> [accordion] link\_repository
>
> **May change state.** Link a project to one of the GitHub account's repositories, at the newest commit of branch (the repository's default when absent), so the person and agents know which code it runs. Push to that repository with git; providers that build from it deploy the push themselves.

> [accordion] link\_folder
>
> **May change state.** Link a project to the local folder its code is in, so the person and agents know which code it runs. Call it after making something at a provider from a folder (an image you built, a pod or function you created), since the provider doesn't say where its code came from.

> [accordion] get\_log\_history
>
> **Read-only hint.** Read up to 100 retained log records for a resource in a fixed time range, as the resource's provider keeps them (for some providers, only the latest deployment's). Retention and sampling may omit events. Follow next\_cursor with the same query.

> [accordion] get\_resource
>
> **Read-only hint.** Read a resource's recorded dependencies, consumers, domains, latest usage and latest recorded release. Does not refresh providers or prove that release is currently serving.

> [accordion] get\_database
>
> **Read-only hint.** Read database branches and compute state without waking or connecting to the database, on providers that report them. No credentials or inferred wake counts are returned. For any other provider's database (tables, backups, settings, queries), use list\_provider\_operations with its resource\_id.

> [accordion] get\_logs
>
> **Read-only hint.** Capture up to 100 redacted live log records over five seconds from a resource whose provider has live logs; no historical backfill (use get\_log\_history).

> [accordion] get\_deployment\_request
>
> **Read-only hint.** Inspect your committed deployment request by UUID without secret inputs or resubmission. A missing result is not proof an in-flight submission cannot still commit; a null deployment means accepted history was removed.

> [accordion] get\_deploy
>
> **Read-only hint.** Read deployment progress and release metadata.

> [accordion] wait\_for\_deploy
>
> **Read-only hint.** Wait until a deploy finishes (live, failed or stopped), up to timeout\_seconds (default 60, at most 120), checking every 5 seconds. Works for Hoista's deploys and for deploys at a watched provider (ids from get\_provider\_details). Returns finished true with the result, or finished false with the current status: then call it again. Use this to keep checking a deploy instead of shell loops or sleeps.

> [accordion] replace\_environment
>
> **May change state.** Queue a reviewed project deployment with new environment values for every runtime resource. Values stay in memory; restart requires resubmission. Managed bindings cannot be replaced.

> [accordion] delete\_secret
>
> **May change state.** Remove one hosted secret from a managed resource, or a variable of a watched resource whose provider allows it. Does not edit source or rebuild browser assets. Managed bindings and active deployments are rejected.

> [accordion] set\_secret
>
> **May change state.** Send a secret directly to its provider. Never returns its value. On a watched resource this sets the variable at the provider, which may redeploy to apply it.

> [accordion] set\_secrets
>
> **May change state.** Set many variables or secrets at once on any resource (resource\_id): on a Worker or Fly app they become secrets, elsewhere service variables. On a watched resource they can instead be its provider project's shared variables (shared: true), optionally without redeploying (redeploy: false). For secrets pass env\_file, the absolute path of a .env file (and names to pick some): Hoista reads the values itself, so they never pass through you or this conversation. Values go straight to the provider and are never returned. A value like \$\{\{Postgres.DATABASE\_URL}} references another service.

> [accordion] delete\_shared\_variable
>
> **May change state.** Delete one of the provider project's shared variables, by name, for the watched resource's provider project and environment.

> [accordion] redeploy\_resource
>
> **May change state.** Watched projects: build and start a resource's current version again at its provider, as its Redeploy button does. Use after changing variables or when it crashed.

> [accordion] restart\_resource
>
> **May change state.** Watched projects: restart a resource's running deployment without rebuilding.

> [accordion] rollback\_resource
>
> **May change state.** Watched projects: serve an earlier deployment of a resource again. Take deployment\_id from get\_provider\_details.

> [accordion] deploy\_latest\_commit
>
> **May change state.** Watched projects: deploy the newest commit of the repository the resource is linked to at its provider. Push your changes first.

> [accordion] deploy\_commit
>
> **May change state.** Watched projects: deploy one commit (full hash) of the resource's linked repository.

> [accordion] deploy\_folder
>
> **May change state.** Watched projects: upload the project's linked folder (or a subfolder of it, such as backend) and deploy it, as the provider's own CLI does; .gitignore and the provider's own ignore file are respected. Use after fixing code locally. Then watch get\_provider\_details and get\_logs until it's live.

> [accordion] stop\_resource
>
> **May change state.** Watched projects: stop a resource's running deployment. It stays stopped until the next deploy.

> [accordion] configure\_resource
>
> **May change state.** Watched projects: change how a resource builds and runs: start\_command, build\_command, root\_directory, cron\_schedule, healthcheck\_path, replicas (1–20), region, restart\_policy (on\_failure, always, never). Only the fields given change; they apply on the next deploy.

> [accordion] connect\_repo
>
> **May change state.** Watched projects: make a resource deploy from a GitHub repository (owner/name, optional branch) from now on.

> [accordion] add\_resource\_domain
>
> **May change state.** Watched projects: give a resource an address. With domain, adds your own domain (then point its DNS at the record list\_domains shows); without, adds a free address from the provider. Optional port the service listens on.

> [accordion] rename\_resource\_domain
>
> **May change state.** Watched projects: give the provider's own address a new name (to: the new address or just its first label). Custom domains can't be renamed: add the new one, then remove the old.

> [accordion] remove\_resource\_domain
>
> **May change state.** Watched projects: remove one of a resource's addresses, as listed by get\_provider\_details. Needs the person's approval: the first call returns pending with an approval\_id; retry with it once they allow it in Hoista.

> [accordion] update\_resource\_domain
>
> **May change state.** Watched projects: change the port one of a resource's addresses sends traffic to.

> [accordion] retry\_domain\_certificate
>
> **May change state.** Watched projects: ask the provider to issue a custom domain's TLS certificate again after it failed.

> [accordion] disconnect\_source
>
> **May change state.** Watched projects: stop a resource deploying from its repository or image.

> [accordion] add\_volume
>
> **May change state.** Watched projects: attach a persistent disk to a resource, mounted at an absolute path such as /data.

> [accordion] remove\_volume
>
> **May change state.** Watched projects: delete a resource's volume and all data on it (volume ids from get\_provider\_details). Needs the person's approval: retry with the approval\_id once they allow it in Hoista.

> [accordion] add\_tcp\_proxy
>
> **May change state.** Watched projects: open a public TCP endpoint to a port a resource listens on (for databases and non-HTTP projects). The endpoint shows in get\_provider\_details.

> [accordion] remove\_tcp\_proxy
>
> **May change state.** Watched projects: close a public TCP endpoint (ids from get\_provider\_details). Needs the person's approval.

> [accordion] rename\_private\_host
>
> **May change state.** Watched projects: rename a resource's private network address, which other services in the provider project reach it at.

> [accordion] remove\_service
>
> **May change state.** Watched projects: delete a resource at its provider for good, for providers whose capabilities include delete: a Railway or Render service, a Vercel or Supabase project, a Worker, Pages project, D1 database, empty R2 bucket or zone on Cloudflare, a Fly app, a Neon project or a Resend sending domain. Data in it is gone. Needs the person's approval: the first call returns pending with an approval\_id; retry with it once they allow it in Hoista.

> [accordion] create\_service
>
> **May change state.** Watched projects: create a new service in the same project as the project's other services, empty or from a GitHub repo (owner/name, optional branch) or a Docker image. It joins the project.

> [accordion] add\_database
>
> **May change state.** Watched projects: add a database or any template next to the project's services: code postgres, mysql, redis or mongo (or another template code). Optional variables fill the template's required values. The new services join the project; connect them with set\_secret using a reference such as \$\{\{Postgres.DATABASE\_URL}}.

> [accordion] add\_to\_project
>
> **May change state.** Make something new at a provider and add it to an existing project, so one project can have pieces on every provider. kind: repo (a provider builds a GitHub repo; capability new\_project; runs\_as web, static, worker or cron where the provider offers them), folder (the provider's own tool deploys a folder on this computer; new\_from\_folder), database (engine postgres, mysql, redis or mongo; new\_database), bucket (new\_bucket), email\_domain (a domain to send email from; new\_email\_domain; returns the DNS records to add), image (a container image; on a provider with both, gpu for a GPU machine or cpu and vcpus for a CPU-only one; new\_from\_image). get\_my\_access shows each connected account and what it can make. Where the project already has a resource on that account, the new one is made next to it. For a project that already exists (get\_my\_access shows the folder's active\_project), add to it; create\_project only for a new one. Call this once per piece. For code, follow with get\_provider\_details and wait\_for\_deploy. Connect pieces with set\_secret.

> [accordion] create\_bucket
>
> **May change state.** Watched projects: create an object storage bucket in the project's provider project.

> [accordion] list\_import\_candidates
>
> **Read-only hint.** List unassigned discovered resources, or pass ignored=true to inspect resources set aside locally. No provider activity is inferred.

> [accordion] set\_resource\_ignored
>
> **May change state.** Set aside or restore one unassigned import candidate. Reversible local visibility only; never deletes, pauses or changes its provider resource.

> [accordion] resolve\_resources
>
> **Read-only hint.** Read candidate resources matching exact names, IDs, provider project stems or hostnames in a description. Always review account/ownership and choose explicit IDs before grouping.

> [accordion] link\_resources
>
> **May change state.** Connect explicit from\_resource/to\_resource/via endpoints, or resolve a description into resource candidates. To group reviewed candidates, repeat description with project\_id, resource\_ids and review\_token. Ambiguity requires explicit selection; no cloud resources are changed.

> [accordion] suggest\_imports
>
> **Read-only hint.** Read review-only grouping proposals from shared resource names and exact public hostnames. Ambiguous alternatives require the user's choice; no resources are grouped by this read.

> [accordion] import\_resources
>
> **May change state.** Discover an account or group selected resources in watching mode.

> [accordion] get\_usage
>
> **Read-only hint.** Read daily measured usage per resource since a UTC date (requests, errors, compute, storage), as the provider reported it. For money, use get\_bills: what each provider itself reports.

> [accordion] delete\_project
>
> **May change state.** Request approval to delete a managed project, then retry with its approved approval\_id.

> [accordion] delete\_resource
>
> **May change state.** Request approval to delete a managed resource, then retry with its approved approval\_id.

> [accordion] connect\_account
>
> **May change state.** Request a guided desktop connection. Provider credentials must be entered in Hoista, never in tool arguments.

> [accordion] get\_approval
>
> **Read-only hint.** Read this agent's approval decision. Expired and declined requests cannot execute.

## Permissions and retries

Available actions depend on the agent's access, the project's mode and the provider. Follow any returned approval request. When checking or retrying a call, keep its operation or deployment ID to avoid creating duplicate requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.