# Model Context Protocol

URL: /docs/mcp

Source: https://github.com/easypanel-io/monorepo/blob/main/apps/website/content/docs/mcp.mdx

Connect AI clients to Easypanel through its remote MCP server.



Easypanel includes a remote [Model Context Protocol](https://modelcontextprotocol.io/)
(MCP) server. It lets compatible AI clients inspect and manage Easypanel using
the permissions of a selected Easypanel user.

The server uses Streamable HTTP, so there is no local MCP process to install or
run. Its endpoint is:

```text
https://YOUR_SERVER_DOMAIN/api/mcp
```

Replace `YOUR_SERVER_DOMAIN` with your Easypanel server domain.

## Create a connection [#create-a-connection]

1. In Easypanel, open **Settings → Server → Users**.
2. Select **Generate API Key** for the user the AI client should act as.
3. Select **Connect → MCP** beside that user.
4. Open your AI client's MCP or connector settings.
5. Add a remote **Streamable HTTP** server using one of the authentication
   methods shown below.
6. Save the connection and ask the client to list your Easypanel projects.

### Connection URL [#connection-url]

When a client accepts only an MCP server URL, append the API key to the
endpoint:

```text
https://YOUR_SERVER_DOMAIN/api/mcp/YOUR_API_KEY
```

The **Connect → MCP** dialog provides the complete URL for the selected user.

### Bearer authentication [#bearer-authentication]

When a client supports custom HTTP headers, prefer the endpoint without the
key in its path:

```text
Server URL: https://YOUR_SERVER_DOMAIN/api/mcp
Authorization: Bearer YOUR_API_KEY
```

For a client that stores MCP configuration as JSON, the equivalent shape is:

```json
{
  "mcpServers": {
    "easypanel": {
      "url": "https://YOUR_SERVER_DOMAIN/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

The exact property names can differ between clients. Select Streamable HTTP as
the transport and use the URL and header values above.

<Callout type="warn">
  The connection URL and Authorization header contain a user API key. Treat
  either form like a password. Prefer an encrypted secret or environment
  variable when the client supports one, and revoke the API key immediately if
  it is exposed.
</Callout>

## How the MCP server works [#how-the-mcp-server-works]

Easypanel exposes four stable MCP tools rather than publishing every operation
as a separate tool:

| Tool                  | Purpose                                                                            |
| --------------------- | ---------------------------------------------------------------------------------- |
| `search_procedures`   | Find available Easypanel operations and their exact input schemas                  |
| `execute_query`       | Run a read-only operation returned by `search_procedures`                          |
| `execute_mutation`    | Run a non-destructive change                                                       |
| `execute_destructive` | Run an operation that can delete, overwrite, restore, revoke, or disrupt resources |

The client should search before executing an unfamiliar operation. For
example, a request to restart a Compose service first searches for `restart
compose service`, then calls the returned procedure with the required project
and service names.

Separating execution by risk lets MCP clients distinguish reads,
non-destructive changes, and destructive changes. Compatible clients can use
the tool annotations to request additional approval before calling
`execute_destructive`.

Only operations explicitly enabled for MCP appear in search results. The
catalog follows the installed Easypanel version, so new capabilities can become
available without changing the four MCP tool names.

## Permissions and safety [#permissions-and-safety]

An MCP connection acts as the user whose API key it contains. Project access
and administrator checks are enforced in the same way as other authenticated
Easypanel operations.

* If your license supports multiple users, create a dedicated user when you
  want to limit the projects available to an AI client.
* Review the target project, service, and environment before approving a
  destructive operation.
* Assume procedure inputs and results may contain credentials, environment
  variables, configuration, or executable content.
* Do not paste API keys, secret output, or connection URLs into prompts,
  screenshots, issue reports, or source control.
* Revoke unused API keys from **Settings → Server → Users**.

<Callout type="info">
  Regenerating or revoking a user's API key immediately invalidates MCP clients
  configured with the previous key. Update the connection with the new key to
  restore access.
</Callout>

## Troubleshooting [#troubleshooting]

### The client receives `401 Unauthorized` [#the-client-receives-401-unauthorized]

Confirm that you are using a generated user API key, not a browser session
token. Check that the key has not been revoked or regenerated. For header-based
authentication, the value must use the exact `Bearer YOUR_API_KEY` format.

### The client cannot connect [#the-client-cannot-connect]

Verify that the panel URL is reachable from the machine or hosted client and
uses a valid HTTPS certificate. Confirm that the client supports remote
Streamable HTTP MCP servers; a client that supports only local stdio servers
cannot connect directly.

### A procedure is missing [#a-procedure-is-missing]

Ask the client to call `search_procedures` with a short action-and-resource
query, such as `list projects` or `restart compose service`. Procedures that are
not available in the installed Easypanel version, or that are intentionally
disabled for MCP, do not appear in results.

### An operation is rejected [#an-operation-is-rejected]

Use the execution tool required by the search result: `execute_query`,
`execute_mutation`, or `execute_destructive`. Also verify that the selected
user has access to the target project and permission to perform the operation.