MCP server

Let Claude, Cursor, Codex or any other MCP client manage your HostStack team — deploy, read logs, add databases and domains — with the same permissions as an API key.

How it works

The HostStack MCP server exposes 132 tools over the Model Context Protocol. Every tool call goes through the same API routes as the dashboard, the CLI and the SDK, so permissions, rate limits and the activity log apply the same way.

You can run it two ways, with the same tools either way:

	Hosted	Local
Where	`https://hoststack.dev/api/mcp`	`npx -y @hoststack.dev/mcp`
Transport	Streamable HTTP, stateless	stdio
Auth	`Authorization: Bearer hs_live_...` header	`HOSTSTACK_API_KEY` environment variable
Install	Nothing	Node.js 18 or later

The API key decides everything: it is bound to one team, so no tool takes a team id, and a tool can only do what the key is allowed to do.

Connect a client

Create an API key
In the dashboard, open Settings → API keys and create a key with Full Access permission. The default, Deploy Only, is refused by the tools that need full access, with This endpoint requires an API key with full_access permission.

Add the server to your client

Pick your client. The local tabs run the server on your machine with npx; the hosted tab needs nothing installed.

claude mcp add hoststack --env HOSTSTACK_API_KEY=hs_live_... -- npx -y @hoststack.dev/mcp

{
  "mcpServers": {
    "hoststack": {
      "command": "npx",
      "args": ["-y", "@hoststack.dev/mcp"],
      "env": {
        "HOSTSTACK_API_KEY": "hs_live_..."
      }
    }
  }
}

{
  "mcpServers": {
    "hoststack": {
      "command": "npx",
      "args": ["-y", "@hoststack.dev/mcp"],
      "env": {
        "HOSTSTACK_API_KEY": "hs_live_..."
      }
    }
  }
}

# ~/.codex/config.toml
[mcp_servers.hoststack]
url = "https://hoststack.dev/api/mcp"
bearer_token_env_var = "HOSTSTACK_API_KEY"

{
  "mcpServers": {
    "hoststack": {
      "type": "http",
      "url": "https://hoststack.dev/api/mcp",
      "headers": { "Authorization": "Bearer hs_live_..." }
    }
  }
}

Claude Desktop reads ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Cursor reads ~/.cursor/mcp.json. Restart the client after editing either.

Check the connection
Ask the agent which HostStack team it is connected to. It calls get_me and answers with your team’s name.

Generate a config snippet

The package prints the config for three clients, so you don’t have to type it. If HOSTSTACK_API_KEY is set in your shell it goes into the snippet; otherwise you get a placeholder to replace.

bash

npx -y @hoststack.dev/mcp --print-config claude-code
npx -y @hoststack.dev/mcp --print-config claude-desktop
npx -y @hoststack.dev/mcp --print-config cursor

claude-code prints a claude mcp add command and claude-desktop a whole config file. cursor prints only the hoststack entry — paste it inside mcpServers. --help and --version also work without a key.

Local server settings

These apply to the local server only; the hosted one reads the header.

HOSTSTACK_API_KEY

stringrequired

An hs_live_... or hs_test_... key. Needed to serve; not needed for --help, --version or --print-config.

HOSTSTACK_BASE_URL

string

The API host the tools call.

Default: https://hoststack.dev

HOSTSTACK_MCP_TRACE

string

Set to 1 to write one JSON line per tool call — tool, duration, ok or error — to stderr, for a local trace (2> mcp-trace.log). Nothing is sent to HostStack.

Prompts and resources

Besides tools, the server offers three prompts your client can list and run:

diagnose_failed_deploy service_id: Finds a service’s most recent failed deploy, reads its logs and proposes a fix. It stops at the suggestion and never redeploys on its own.
deploy_status_check: A short status report: who you are, what’s running, what’s deploying, and recent activity.
rotate_secret service_id, key: Rotates one secret env var. The agent asks you for the new value instead of generating it, and asks before redeploying.

And one resource, hoststack://team: the team, the user behind the key, project and service counts, and the first ten of each — enough for an agent to orient itself without a round of list calls.

Tool reference

132 tools in 22 groups, one section per group below. Read tools change nothing; Write tools create, change or delete something, so clients that ask before acting will ask for these. Each tool’s own description — what your agent sees — carries the full inputs, return shape and examples.

Most tools take the public ids you see in the dashboard (svc_..., prj_..., dpl_...). The error-tracking, uptime and site tools take numeric ids instead, which their list tools return.

Identity and build

Tool	Access	What it does
get_me	Read	The user and team the API key is bound to.
describe_mcp	Read	The server’s package version, how many tools it registers, and whether the dev box tools are present. Touches no account data.

Call get_me first in a session to confirm which team the key acts on.

Projects

There is no delete_project: deleting a project takes every service, database, domain and volume under it, and that is a confirmation a person should give in the dashboard. Everything one level down can be deleted by an agent.

Services and dev boxes

Tool	Access	What it does
list_services	Read	Services in the team, filterable by project, environment, status, type and dev box.
get_service	Read	One service with its status and full config: resources, health check, scaling, restart policy.
get_service_metrics	Read	Latest CPU, memory, network and request rate.
get_service_metrics_history	Read	CPU, memory, network and disk as a time series.
list_dev_environments	Read	The team’s dev boxes, each with its companion services.
list_templates	Read	Stack templates (Next.js, Django …) and one-click apps (WordPress, Ghost, n8n …) that create_service accepts.
create_service	Write	Create a service from a Git repo or a prebuilt Docker image, with env vars and links in the same call.
create_dev_environment	Write	Create a dev box inside a project, with a persistent /workspace and the API keys set, and start it.
create_standalone_dev_environment	Write	Create a dev box in the team’s Development area from a GitHub repo, any clone URL or blank, with optional Postgres, Redis or Meilisearch.
spin_up_dev_environment	Write	Create a dev box from an existing service: repo cloned, env vars copied, linked database cloned.
resize_dev_environment	Write	Move a dev box (or any service) to a different size.
set_dev_box_hardware	Write	Give a dev box on your own machine that machine’s graphics card, or all of its memory instead of its plan’s.
delete_dev_environment	Write	Delete a dev box together with its cloned database and /workspace volume.
update_service	Write	Rename a service.
update_service_config	Write	Change build and runtime config: commands, branch, health check, resources, scaling, plan, log filter rules.
suspend_service	Write	Stop all instances and pause auto-deploys; the config is kept.
resume_service	Write	Start a suspended service and re-enable auto-deploys.
delete_service	Write	Delete a service with its volumes, env vars, domains and deploy history. Irreversible.

A dev box is a cloud workspace an agent codes in. It is not a project environment — create_environment with type "development" makes a deploy target next to production and staging, not a box.

Deploys

Tool	Access	What it does
list_deploys	Read	A service’s deploys, newest first.
get_deploy	Read	One deploy: status, commit and timestamps.
get_deploy_logs	Read	Build and deploy log for one deploy, paged.
diagnose_deploy	Read	The deploy record, the build log tail and the runtime log tail from the deploy’s start, in one call.
trigger_deploy	Write	Deploy the branch head, or a given commit or branch.
cancel_deploy	Write	Stop a running deploy; the previous release keeps serving.

get_deploy_logs returns up to 500 log entries per call (at most 5,000) and a nextAfterId cursor; pass it back as after_id for the next page.

Runtime logs

Tool	Access	What it does
get_service_logs	Read	Recent runtime output (stdout/stderr), filterable by time, stream, level and text, or just counted.
get_service_logs_bulk	Read	The same for several services at once, keyed by service id.

Logs are snapshots, not a stream: get_service_logs returns the last 200 lines by default and at most 1,000. Call it again for newer lines, or use the service’s Logs tab to follow live.

Environments

Tool	Access	What it does
list_environments	Read	A project’s environments: production, staging, development, preview.
create_environment	Write	Create an environment in a project.
update_environment	Write	Rename it, protect it, or make it the project default.
delete_environment	Write	Delete an environment.
promote_deploy	Write	Run an already-built deploy in another environment, without rebuilding.

Databases

Tool	Access	What it does
list_databases	Read	Managed databases in a project.
get_database	Read	One database: status, engine, version. No credentials.
get_database_cluster	Read	Members and failover history of an HA Postgres cluster.
list_database_backups	Read	The off-site archives a database can be restored from.
query_database	Read	Run one read-only SQL statement against a managed Postgres.
create_database	Write	Provision Postgres, Redis, MySQL, MariaDB or MongoDB in a project.
update_database	Write	Rename, change plan, or grow the disk.
delete_database	Write	Delete a database and all its data.
suspend_database	Write	Stop the container and keep the data.
resume_database	Write	Start a suspended database; its URL is unchanged.
restart_database	Write	Restart in place — a few seconds of downtime, same URL.
upgrade_database_to_ha	Write	Migrate a single-node Postgres to a three-node HA cluster.
upgrade_database_version	Write	Upgrade Postgres or Redis to a newer major version in place; URLs stay valid.

No tool returns database credentials — an app gets them by being linked (see Resource links), and query_database runs read-only SQL without the password ever reaching the agent. The nightly off-site dump is a schedule; list_database_backups is the evidence that one exists.

Resource links

Tool	Access	What it does
list_managed_resources	Read	Every managed resource in the team — databases, buckets, queues, search, email domains — with the numeric id a link needs.
list_service_resources	Read	What is linked to a service and injected on deploy.
link_resource_to_service	Write	Inject a resource’s connection details into a service as env vars.
unlink_resource_from_service	Write	Remove a link; the resource itself is kept.

The middle step of adding a database: create_database, then link_resource_to_service, then trigger_deploy. A link injects DATABASE_URL, REDIS_URL or MONGO_URL on the next deploy.

Volumes

Tool	Access	What it does
list_volumes	Read	Persistent disks attached to a service.
list_volume_backups	Read	The archives a volume can be restored from.
create_volume	Write	Attach a disk; it is mounted on the next deploy.
update_volume	Write	Change the mount path, grow the size, or switch backups on or off.
delete_volume	Write	Detach a volume and destroy the disk.
restore_volume	Write	Unpack an archive over the volume. Destructive, not reversible.

backup_enabled says backups are being taken; list_volume_backups says which ones exist. A volume backup is a file-level copy of a live disk, taken file by file with nothing paused — not a point-in-time snapshot — so a database running on a volume wants its own dump as well.

Environment variables

Tool	Access	What it does
list_env_vars	Read	A service’s variables, secrets masked.
set_env_var	Write	Create or update one variable by key.
delete_env_var	Write	Delete one variable by key.
bulk_set_env_vars	Write	Add or update several variables at once; others are left alone. mode "replace" also removes every variable not listed, and returns the removed keys.

set_env_var and delete_env_var take the key (case-sensitive), not an id. list_env_vars masks secret values as ••••••, on the server, so secrets never reach the agent.

Domains

Tool	Access	What it does
list_domains	Read	Every custom domain in the team.
add_domain	Write	Attach a hostname, optionally to a service; returns the DNS targets.
verify_domain	Write	Check the DNS targets and issue the certificate.
update_domain	Write	Make a domain the service’s primary hostname, or change SSL, redirect and trailing-slash handling.
remove_domain	Write	Detach a hostname; it stops routing immediately.

DNS

Tool	Access	What it does
list_dns_zones	Read	Hosted DNS zones.
list_dns_records	Read	Every record in a zone.
get_dns_record	Read	One record, with its sync status.
check_dns_delegation	Read	Whether the parent registry really delegates the zone to HostStack, read live.
create_dns_record	Write	Create a record.
update_dns_record	Write	Change a record’s type, name, value, TTL or priority.
delete_dns_record	Write	Delete a record.
resync_dns_record	Write	Re-push a record stuck at failed without changing it.

A zone can be active, signed and full of correct records while the registry still points the domain at its previous host. check_dns_delegation reads the registry live — run it first when a zone looks healthy but the site is not live, a domain will not verify or a certificate will not issue.

Your own machines

Read-only on purpose: enrolling a machine means running an installer on it, which needs a person at that machine. Use the dashboard or `hoststack machines add`. The tools give an agent the machine id to pass as `machine` when creating a service, database or dev box.

Cron

Dev box tasks

Tool	Access	What it does
list_dev_tasks	Read	A project’s task backlog.
get_dev_task	Read	One task with its full prompt.
list_dependency_status	Read	How far behind every repo is: the latest weekly dependency scan per repo, advisories and majors.
create_dev_task	Write	File a task, optionally pinned to a dev box.
update_dev_task	Write	Edit a task, or mark it done or back to idea.
update_dependency_updates	Write	Turn weekly dependency updates on or off, pick the box that runs them, allow auto-ship.

A project’s agent backlog — the list under Development → Tasks. Queue work for a box from outside it, or read back what it did.

Alerts and notification channels

Tool	Access	What it does
list_alerts	Read	Recent alerts: failed deploys, health and uptime failures, new errors, certificate and backup failures and more.
list_notification_channels	Read	Slack, Discord and email channels, with the events each receives.
create_notification_channel	Write	Create a channel and subscribe it to events.
update_notification_channel	Write	Rename, turn on or off, or change events. The URL and type cannot change.
delete_notification_channel	Write	Delete a channel.
test_notification_channel	Write	Send a test message to a channel.

Error tracking

Tool	Access	What it does
list_error_issues	Read	Exceptions your apps reported, grouped by cause.
get_error_issue	Read	One issue with its recent stack traces.
list_ingest_keys	Read	A service’s error-ingest keys (prefixes only).
update_error_issue	Write	Resolve, ignore or reopen an issue.
fix_error_in_dev_box	Write	Turn an issue into a coding-agent task in the project’s dev box.
create_ingest_key	Write	Mint a write-only key a service reports errors with.
delete_ingest_key	Write	Revoke an ingest key immediately.

Uptime checks

Tool	Access	What it does
get_uptime_check	Read	A service’s uptime check and its last result.
set_uptime_check	Write	Create or change a service’s uptime check.
delete_uptime_check	Write	Remove the check. An open alert is left as it stands.

Not the deploy-time health check: an uptime check requests the service’s public URL from outside, on a schedule.

Web analytics

Tool	Access	What it does
list_analytics_sites	Read	Tracked sites, their keys, retention and service.
check_analytics_site	Read	Why a site is reporting nothing.
get_analytics_summary	Read	Visitors, pageviews, bounce rate and visit length per site, against the previous period.
get_analytics_overview	Read	The full breakdown for a site: paths, referrers, events, devices, countries, campaigns.
get_search_console_overview	Read	Google Search clicks, impressions, queries and index state for sites linked to Search Console, against the previous period.
get_search_console_detail	Read	One page’s queries, or one query’s pages, with its daily series and the previous period.
get_search_console_status	Read	Whether a site’s Search Console link is pending, active, still pulling its first 90 days, or broken.
get_bing_overview	Read	Bing clicks and impressions per day, weekly top queries and pages, crawl figures and sitemaps.
get_bing_status	Read	Whether a site is linked to Bing, still pulling, or paused for a missing key or unverified site.
get_site_uptime_check	Read	A tracked site’s uptime check.
get_site_audit	Read
get_keyword_opportunities	Read
research_keywords	Read
get_google_ads_status	Read	Whether the team’s Google Ads is connected for Keyword Planner volumes and click prices.
create_analytics_site	Write	Start tracking a domain; returns the script tag.
update_analytics_site	Write	Change origins, name, retention or service.
purge_analytics_paths	Write	Delete what a site recorded under one path, e.g. a leaked token.
verify_site_domain	Write	Prove you own a site’s domain with a TXT record.
set_site_uptime_check	Write	Watch a site hosted elsewhere and alert when it stops answering.
connect_search_console	Write	Start linking a site to Search Console; returns a link the owner opens to finish it.
disconnect_search_console	Write	Unlink a site from Search Console, remove its search data and revoke the Google grant.
connect_bing	Write	Link one site, or every site, to Bing Webmaster Tools with the team’s saved Bing key.
disconnect_bing	Write	Unlink a site from Bing and remove its Bing data.
disconnect_google_ads	Write	Remove the team’s Google Ads connection.
run_site_audit	Write

These read traffic; they do not record it — pageviews are sent with a public site key and never pass through this server. Beyond a site’s raw-event window, visitors are summed daily uniques; check visitorsAreSummedDailies before quoting a 90-day or 12-month visitor number.

Activity log

GitHub

A repo’s github_repo_id is a HostStack id, not GitHub’s, and list_github_repos is the only place to read it. create_service also accepts the owner/name form directly.

Support

For a fault in the platform, not a bug in your own code. Pass serviceId and the service, its latest deploy and that deploy’s last 40 log lines are attached server-side.

Limits and telemetry

The hosted endpoint accepts API keys only — a dashboard session cookie gets 401 API key required for /api/mcp — and allows 120 requests a minute.
For hosted calls HostStack records one row per tool call: the tool name, duration, success or error, and a hash of the arguments — never the arguments themselves. The rows feed on-call alerts on tool error spikes and are deleted after 30 days.
The local server records nothing on HostStack’s side.

Troubleshooting

Dev box tools are missing: A stale npx cache can keep serving an old build. Ask the agent to call describe_mcp: if devEnvToolsPresent is false, run npx -y @hoststack.dev/mcp@latest once, or clear the npx cache, and restart the client.
HOSTSTACK_API_KEY is required to serve: The local server started without a key. Put it in the client’s env block rather than only exporting it: a client started from a desktop launcher, like Claude Desktop, never sees your shell’s variables.
No team bound to API key: The key isn’t tied to a team. Create a new one under Settings → API keys.
requires an API key with full_access permission: The key is Deploy Only. Create a Full Access key and swap it in. A few owner-only actions, such as billing, can’t be done with any API key.

Next steps

Was this page helpful?

Tool	Access	What it does
list_projects	Read	Every project in the team.
get_project	Read	One project by id.
create_project	Write	Create a project.
update_project	Write	Rename a project or change its description.

Tool	Access	What it does
list_machines	Read	Your enrolled machines, whether they are online, and counts of what runs on each.
get_machine	Read	One machine and everything running on it.

Tool	Access	What it does
list_cron_executions	Read	Recent runs of a cron job, newest first.
get_cron_execution	Read	One run: status, exit code, timing.

Tool	Access	What it does
list_github_repos	Read	Repositories the team can deploy, with the id create_service takes.
sync_github_repos	Write	Re-read the repository list from GitHub, after pushing a new repo.