MCP server

Lunary Cloud has a built-in Model Context Protocol server. An AI agent connected to it can inspect and operate your services with the same authorization as the REST API: same scopes, same audit trail.

Endpoint

POST https://lunary.cloud/api/v1/mcp
Authorization: Bearer lc_your_token_here

• Transport: Streamable HTTP, one JSON-RPC 2.0 message per POST. The server never initiates messages, so there is no SSE stream to hold open.
• Protocol versions: 2025-06-18 and 2025-03-26.
• Auth: either credential below. Each tool enforces the same scope as its REST counterpart.

Authentication

Two credentials work:

• An API token (lc_…) minted under Access → API tokens, passed as a bearer header. See Authentication.
• OAuth. A request without a token gets a 401 whose WWW-Authenticate header points at /.well-known/oauth-protected-resource. Clients that support MCP authorization follow it, open a browser sign-in on lunary.cloud, and come back with an access token. Its scopes match your role in the organization; revoke it by removing the member or their sessions.

Configuring a client

Claude Code, with an API token:

claude mcp add --transport http lunary-cloud https://lunary.cloud/api/v1/mcp \
  --header "Authorization: Bearer lc_your_token_here"

Clients configured with JSON:

{
  "mcpServers": {
    "lunary-cloud": {
      "type": "http",
      "url": "https://lunary.cloud/api/v1/mcp",
      "headers": { "Authorization": "Bearer lc_your_token_here" }
    }
  }
}

Omit the header to use OAuth instead, if the client supports it.

Tools

Tool	Scope	Destructive
list_instances, get_instance, list_catalog, list_registries, list_domains, list_hostnames, get_registry, list_images	read_instances	none
create_instance, delete_instance, update_instance_image, update_instance_config, set_instance_address, add_registry, delete_registry, add_domain, verify_domain, remove_domain, add_hostname, verify_hostname, remove_hostname	write_instances	delete_instance, update_instance_image, update_instance_config, set_instance_address, delete_registry, remove_domain, remove_hostname
list_plugs, list_runs, get_run, get_artifact_url, list_routines	read_plugs; get_run also accepts write_instances, for the runs that scope's own writes return (see below)	none
trigger_plug, configure_routine, trigger_routine	write_plugs	trigger_plug (when list_plugs reports the plug as dangerous), trigger_routine
get_billing_status, list_invoices	read_billing	none
delete_image_tag	push_images	delete_image_tag

A token minted only to provision and tear down can still poll what it started: create_instance, delete_instance, update_instance_image, update_instance_config and set_instance_address each return a run_id, and get_run accepts write_instances alone for those runs: the instance's apply_service, teardown_service and redeploy runs. Any other run (a backup, a sync, a credential rotation) still needs read_plugs, as do list_runs and get_artifact_url; a write_instances-only token asking get_run for one of those gets insufficient_scope: read_plugs.

The server's own tools/list response is authoritative. Connect a client and list the tools to see exactly what is deployed. scope is not a field in that response (only some tool descriptions name one in prose), so the table above is the full mapping. Each tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); the Destructive column is destructiveHint. They are hints a client may use to confirm before acting (openWorldHint is true only for the two DNS verifies). Scopes remain the control.

Every run started over MCP or REST records the credential that started it in triggered_by: mcp:acme/claude-code#42 or api:acme/ci#42 for a token, mcp:acme/user_01… for an OAuth session. The run page and the Activity tab show it beside the trigger.

list_catalog, create_instance, delete_instance and the registry tools take the same fields and return the same codes as GET /catalog, POST /instances, DELETE /instances/{slug} and /registries. See Services & instances.