MCP server

heyo-mcp is a Model Context Protocol server that gives coding agents such as Claude Code tools for HWS sandboxes, app-lb deployments, app-obs logs and metrics, ci runs and the artifact store.

What it is

The server lives in mcp/ (TypeScript, Node 22). It exposes two kinds of tool:

• Sandbox tools use the Heyo cloud API to boot a microVM, run commands in it, and move files in and out.
• Fleet tools operate on app-lb, app-obs, ci and the artifact store. Several diagnostic tools answer questions that span services. For example, diagnose_empty_pool combines app-lb's pool state, app-obs's logs and the metrics that explain why a pool won't fill.

It runs in two modes:

Every service is optional. A service you don't configure still lists its tools, and calling one returns an error naming the variable to set. Sandbox tools are the exception: they are listed only when a usable cloud key is available.

Install

cd mcp
npm install
npm run build        # compiles to mcp/dist/
npm test             # optional: node --test over dist/*.test.js

Claude Code, hosted server

Heyo runs the server at https://mcp.us2.heyo.work/mcp (streamable HTTP). Point Claude Code at it with an app-lb token:

claude mcp add --transport http heyo https://mcp.us2.heyo.work/mcp \
  --header "Authorization: Bearer applb_…"

A namespace user mints that token from the app-lb dashboard's "Get started" card (or App-tokens → New token). It is an admin-tier token confined to their namespace and expires within 90 days; see app-lb auth. The applb_* tools work with it. The app-obs and ci tools do not yet, because those gates live in the default namespace (see Limits and known gaps).

Claude Code, local server

claude mcp add heyo \
  -e HEYO_API_KEY=heyo_api_… \
  -- node /path/to/hws/mcp/dist/index.js

Or in a project's .mcp.json:

{
  "mcpServers": {
    "heyo": {
      "command": "node",
      "args": ["/path/to/hws/mcp/dist/index.js"],
      "env": {
        "HEYO_API_KEY": "heyo_api_…",
        "APPLB_URL": "http://127.0.0.1:9090",
        "APPLB_TOKEN": "applb_…"
      }
    }
  }
}

Other MCP hosts work the same way: run node /path/to/hws/mcp/dist/index.js over stdio with the variables below in its environment. The server writes logs to stderr only, because stdout carries the protocol. At startup it prints a ready line listing the configured services, plus a CREDENTIAL FAULT banner if a key has the wrong shape (for example an applb_ token in HEYO_API_KEY).

After connecting, call heyo_status first. It reports which services the server can reach and what each says about itself.

Configuration

Minimal configurations

Managed app-lb through Heyo cloud. One key covers sandboxes and deployments, and the namespace is discovered from the key on first use:

HEYO_API_KEY=heyo_api_…

If the key can see several namespaces, discovery fails and lists them. Set APPLB_NAMESPACE to choose one.

Self-hosted HWS fleet, run on the app-lb host:

APPLB_URL=http://127.0.0.1:9090
APPLB_TOKEN=applb_…
APP_OBS_URL=http://127.0.0.1:9600
APP_OBS_API_TOKEN=…
CI_URL=http://127.0.0.1:9555
CI_TOKEN=…
ART_URL=http://127.0.0.1:8090
ART_API_KEY=…

Credentials

Four kinds of credential are involved. They are not interchangeable.

App token scopes

An app-lb app token has two independent scopes, checked in different places:

• Admin tier (none, view, admin) is checked by app-lb's admin API. view covers only /metrics, /disks, /feeds, /security, /ingress and /storage, which serve applb_metrics, applb_disks, applb_security_events and the feed tools. Everything else needs admin.
• Deployment scope (a deployments list and/or a namespace) is checked by each deployment's own gate.

There is no read-only tier for deployments. GET /deployments requires admin, because specs can hold secrets. So a token that can run applb_get_deployment can also run applb_delete_deployment. To narrow a token that needs deployment reads, restrict its deployments list or namespace.

When a call returns 401 or 403, run heyo_whoami. It reports the current credential's admin tier, namespace, deployment scope and expiry, which tells an authentication failure apart from a scope failure.

Tools

65 tools in total. Read-only tools only issue GET requests, which is checked by a test. Destructive tools have descriptions starting with DESTRUCTIVE, and that prefix is what sets destructiveHint. The full generated list with descriptions is in the component README (npm run catalogue regenerates it).

Diagnostics

Deploying

Fleet and pools

Sandboxes

Listed only when a usable heyo_api_… key is available, either configured or forwarded by the caller.

Artifact store

ci

Raw requests

heyo_request (sandboxes only), applb_request, obs_request, ci_request and art_request send arbitrary HTTP to each service. Prefer a named tool: a raw call's intent, including a DELETE, is hidden in its arguments.

Resources and prompts

The server has one prompt, deploy_a_service(kind, id, host?), where kind is vm, site or static. It returns the ordered plan for that backend type.

Deploying with an agent

A typical request is "deploy this service". The agent should do the following:

1. Call applb_spec_schema (or read heyo://applb/deployment-spec) and pick the closest example.
2. Call applb_deploy with the full spec. In managed or namespace-scoped use, include "namespace": "<ns>": a spec without one means default.
3. Watch the job it returns with applb_job.

A minimal vm deployment that builds from a Dockerfile:

{
  "id": "hello",
  "namespace": "team-a",
  "routes": [{ "host": "hello.example.com" }],
  "vm": {
    "driver": "firecracker",
    "image": "hello",
    "port": 8080,
    "size_class": "micro",
    "start_command": "setsid nohup /usr/local/bin/hello </dev/null >/var/log/hello.log 2>&1 &"
  },
  "build": {
    "repo": "https://github.com/example/hello.git",
    "ref": "main",
    "dockerfile": "Dockerfile"
  },
  "scaling": { "min_replicas": 1, "max_replicas": 3 },
  "health": { "path": "/health", "timeout_secs": 2 }
}

This follows heyo://applb/examples/git-build.json, which also shows private-repo auth and the remaining scaling fields. app-lb documents the spec in full.

Which job applies depends on the backend:

Choosing the wrong job is refused, not ignored. applb_host_update never updates a managed vm deployment.

TLS: an exact host route gets a certificate automatically within seconds. A host_suffix route needs a fleet wildcard certificate, and without one it is served a fallback certificate that won't validate.

Publishing a build

art_publish performs three requests in order: PUT /blobs/{sha256}, PUT /manifests, then PUT /tags/{tag} with the manifest's digest. The store accepts a tag that points at a blob digest, but nothing can resolve it, so publish with this tool rather than with raw requests. Re-publishing identical bytes only moves the tag.

When the store is behind an app-lb gate, one request carries two credentials: Authorization: Bearer applb_… for the gate (ART_GATE_TOKEN) and x-api-key for the store (ART_API_KEY). On the store's own listener, ART_API_KEY alone is enough.

Hosted mode

Set HEYO_MCP_HTTP_PORT to serve MCP over streamable HTTP at /mcp, with an open GET /healthz that reports the tool count, configured services and credential faults. The transport is stateless (a new server per request), so it works behind a load-balanced pool. Paths other than /mcp and /healthz return 404.

Credential forwarding

A hosted instance can act as each caller rather than as itself:

This prevents a narrowly scoped app token from borrowing the server's broader credential. app-lb re-checks the caller's scope on every request.

For forwarding to app-lb, APPLB_URL must still be set (with no token), so the server knows where app-lb is.

Behind an app-lb gate

HEYO_MCP_REQUIRE_IDENTITY (on by default) makes the server refuse any /mcp request that lacks x-auth-request-user or x-auth-request-email, the headers app-lb sets after a google or jwt gate admits a caller. Each call is logged to stderr with that identity. The server does not re-verify the JWT.

In HTTP mode, art_publish accepts only content_base64: a path would name a file on the server, not the caller's machine.

Deploying it

The repository ships two shapes:

• Host process: mcp/deploy/supervisor/heyo-mcp.conf runs node …/mcp/dist/index.js bound to loopback, and mcp/deploy/heyo-mcp.json registers it with app-lb as a static deployment behind a jwt gate. Make the deployment's upstreams port match HEYO_MCP_HTTP_PORT (the conf uses 9650).
• MicroVM: mcp/deploy/image/Dockerfile builds a rootfs (heyvm mvm build --local-only -f deploy/image/Dockerfile -c . -n heyo-mcp from mcp/). Its init.sh firewalls the listener to the host gateway, and app-lb starts node with the deployment's start_command and env. mcp/deploy/vm.md describes the zero-credential, app-token-gated posture this shape is designed for.

An instance with HEYO_API_KEY set gives every caller the gate admits the same cloud account. Leave it unset for a fleet-operations instance. An app-token gate cannot pass a cloud key through, so sandbox tools won't be listed.

ci behind an app-lb gate

When ci is behind an app-lb gate, its public_paths are only /healthz, /api/submit, /api/runs/, /api/stream/ and /__ui/. Its HTML pages (runs, jobs, runners, VMs, repos) admit browsers only. For that reason:

• ci_run_status and ci_run_logs work against the public hostname with CI_TOKEN. A token for another repository gets 404.
• diagnose_ci_job and the VM tools need ci's own listener. Run the server on the ci host, or tunnel to it:

ssh -N -L 8081:127.0.0.1:8081 ci-host    # then CI_URL=http://127.0.0.1:8081

Pointed at the gated host, those tools fail with this explanation rather than a bare 401.

Limits and known gaps

Troubleshooting

See also

• app-lb and app-lb auth: the deployment spec, gates and app tokens
• heyctl: the CLI for the same APIs
• developer-tools
• Component README