# MCP server

> Connect Claude, Cursor, or any MCP client to your Lunary Cloud services.

Lunary Cloud has a built-in [Model Context Protocol](https://modelcontextprotocol.io) 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

```text
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](/api/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:

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

Clients configured with JSON:

```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 |
| --- | --- |
| `list_instances`, `get_instance` | `read_instances` |
| `update_instance_image` | `write_instances` |
| `list_plugs`, `list_runs`, `get_run`, `get_artifact_url`, `list_routines` | `read_plugs` |
| `trigger_plug`, `configure_routine`, `trigger_routine` | `write_plugs` |
| `get_billing_status`, `list_invoices` | `read_billing` |

The server's own `tools/list` response is authoritative. Connect a client and list the tools to see exactly what is deployed, with each tool's required scope in its description.