@hoststack.dev/mcp

Model Context Protocol (MCP) server for HostStack — let Claude, Cursor, and any other MCP-capable agent deploy services, manage databases, rotate env vars, and read logs on your HostStack team.

Two ways to run it:

• Hosted (recommended) — point your client at https://hoststack.dev/api/mcp with a Bearer API key. No local install.
• Local stdio — npx -y @hoststack.dev/mcp runs the same server in-process and talks JSON-RPC over stdin/stdout.

Quick start

1. Get an API key

Open the dashboard at https://hoststack.dev/dashboard/settings/api-keys and create a key with full_access permission. The key is bound to a single team — every tool call operates on that team automatically; agents never need to pass teamId.

2. Wire it into your client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor

Add to ~/.cursor/mcp.json (or via Settings → MCP):

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

Claude Code

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

Or — equivalently — use the hosted HTTP transport so credentials live only in your Claude Code config, not on disk:

claude mcp add --transport http hoststack https://hoststack.dev/api/mcp --header "Authorization: Bearer hs_live_..."

Any other client (hosted)

POST https://hoststack.dev/api/mcp
Authorization: Bearer hs_live_...
Content-Type: application/json

The endpoint speaks the streamable-HTTP MCP transport. Stateless — every request is independent; no session bookkeeping.

3. Generate config snippets

The CLI knows how to print config for the three big clients so you don't have to memorise the shape:

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

If HOSTSTACK_API_KEY is set in your shell, it gets baked into the snippet; otherwise you'll see a hs_live_your_api_key_here placeholder you can search-and-replace.

--help and --version work the same way — no key needed, because the people most likely to reach for them are the ones who haven't set one up yet:

npx @hoststack.dev/mcp --help
npx @hoststack.dev/mcp --version

Running it with no arguments starts the server on stdio, and that is the one path that does need HOSTSTACK_API_KEY. It speaks JSON-RPC, so it isn't much use by hand — an MCP client is what should be launching it.

Tool inventory

113 tools. The headings are the registry's own categories rather than a friendlier regrouping, so the build can diff this table against the registry and fail when the two disagree — which is how an earlier version of it came to advertise a total from three releases back and send agents to the dashboard for a create_database that had already shipped.

| Category | Read | Write | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | projects | list_projects, get_project | create_project, update_project | | services | list_services, get_service, get_service_metrics, get_service_metrics_history, list_dev_environments, list_templates | create_service, create_dev_environment, create_standalone_dev_environment, spin_up_dev_environment, resize_dev_environment, delete_dev_environment, update_service, update_service_config, suspend_service, resume_service, delete_service | | logs | get_service_logs, get_service_logs_bulk | — | | deploys | list_deploys, get_deploy, get_deploy_logs, diagnose_deploy | trigger_deploy, cancel_deploy | | environments | list_environments | create_environment, update_environment, delete_environment, promote_deploy | | databases | list_databases, get_database, get_database_cluster, list_database_backups, query_database | create_database, update_database, delete_database, suspend_database, resume_database, restart_database, upgrade_database_to_ha, upgrade_database_version | | volumes | list_volumes, list_volume_backups | create_volume, update_volume, delete_volume, restore_volume | | resource-links | list_managed_resources, list_service_resources | link_resource_to_service, unlink_resource_from_service | | machines | list_machines, get_machine | — | | domains | list_domains | add_domain, verify_domain, update_domain, remove_domain | | dns | list_dns_zones, list_dns_records, get_dns_record, check_dns_delegation | create_dns_record, update_dns_record, delete_dns_record, resync_dns_record | | env-vars | list_env_vars | set_env_var, delete_env_var, bulk_set_env_vars | | cron | list_cron_executions, get_cron_execution | — | | dev-tasks | list_dev_tasks, get_dev_task | create_dev_task, update_dev_task | | alerts | list_alerts, list_notification_channels | create_notification_channel, update_notification_channel, delete_notification_channel, test_notification_channel | | errors | list_error_issues, get_error_issue, list_ingest_keys | update_error_issue, fix_error_in_dev_box, create_ingest_key, delete_ingest_key | | uptime | get_uptime_check | set_uptime_check, delete_uptime_check | | analytics | list_analytics_sites, check_analytics_site, get_analytics_summary, get_analytics_overview, get_site_uptime_check | create_analytics_site, update_analytics_site, verify_site_domain, set_site_uptime_check | | activity-log | list_activity_log | — | | github | list_github_repos | sync_github_repos | | support | — | report_issue | | meta | get_me, describe_mcp | — |

describe_mcp returns the same inventory computed from the registry at call time. If this table and that tool ever disagree, the tool is right.

A few design notes worth knowing as a caller:

• set_env_var / delete_env_var are key-based. You don't need an env-var ID; the MCP looks up the existing var by key first, then patches or deletes by ID under the hood.
• list_env_vars masks secret values. Anything stored with is_secret: true comes back as ••••••. The masking happens server-side, so you can't accidentally leak a secret to the agent's context window.
• get_service_logs and get_deploy_logs are snapshots. Streaming logs over MCP isn't supported — re-call the tool to get newer entries. Use the dashboard's /dashboard/services/:id/logs for live tails.
• Databases are provisioned end-to-end. create_database → link_resource_to_service → trigger_deploy is the whole managed-database flow, and the link injects DATABASE_URL / REDIS_URL / MONGO_URL on the next deploy — so the agent never handles a password. Credentials themselves stay in the dashboard; query_database runs read-only SQL without one.
• One deliberate gap: the project cascade. There is no delete_project — deleting a project takes every service, database, domain and volume under it with it, and that is a confirmation a person should give in the dashboard. Everything one level down an agent can do: delete_service, delete_database, delete_volume and delete_environment are all registered, so an agent asked to tear down what it created can.
• Errors are grouped, and the grouping is the product. list_error_issues returns one row per distinct problem, not one per event — the fingerprint is the exception class, the message with its variable parts removed, and the topmost frame in your code rather than the framework's. Counts are exact; the stored occurrences behind them are samples. fix_error_in_dev_box is the one thing a hosted error tracker cannot do: it writes the exception, the marked stack and a real request into a task in the project's dev box, where the repository is already checked out.
• Uptime checks are not health checks. The deploy-time health check watches the container from inside the host and stops mattering once a deploy is live. get_uptime_check / set_uptime_check describe the other one: HostStack requesting the public URL from outside, which is what notices DNS, TLS and routing failures, and a service that accepts a connection and then answers nothing.
• list_machines / get_machine are read-only. Enrolling your own hardware needs a terminal on the machine itself (hoststack machines add), so there is no tool for it — what an agent needs is the other half, the id to pass as machine when it creates a service, database or dev box there.
• Telemetry, hosted only. When you use https://hoststack.dev/api/mcp, we record one row per tool call (tool name, duration, ok/error, SHA-derived hash of input args — never the args themselves) for the analytics page and on-call alerts. Retained 30 days. The local stdio install records nothing.

Environment variables

| Var | Required | Default | Notes | | --------------------- | -------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | HOSTSTACK_API_KEY | yes | — | Bearer token. hs_live_… for prod, hs_test_… for the test team. | | HOSTSTACK_BASE_URL | no | https://hoststack.dev | Override for self-hosted or staging. | | HOSTSTACK_MCP_TRACE | no | unset | Set to 1 to emit one NDJSON line per tool call to stderr. Useful for 2> mcp-trace.log debugging without colliding with the JSON-RPC body on stdout. |

License

MIT — see LICENSE.