Model Context Protocol

Easypanel includes a remote Model Context Protocol (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:

https://YOUR_SERVER_DOMAIN/api/mcp

Replace YOUR_SERVER_DOMAIN with your Easypanel server domain.

Create a connection

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

Connection URL

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

https://YOUR_SERVER_DOMAIN/api/mcp/YOUR_API_KEY

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

Bearer authentication

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

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:

{
  "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.

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.

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

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.

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.

Troubleshooting

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

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

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

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.

Model Context Protocol

On this page