Connecting an AI assistant

How to let an external AI assistant (Claude, an agent, an MCP client) work with your LimePanel: a token with the minimum permissions, ready-to-copy instructions, step-by-step setup and the security rules.

What it is and when you need it#

LimePanel already has a built-in AI assistant: you open it from the panel, it reads what the panel measures, explains problems and proposes fixes that only run once you approve them. For diagnosis and questions about your hosting, that is all you need.

This guide covers the other case: you want your own assistant, the one you already work with, to manage the panel from its chat or from the terminal. For example: "list the sites whose certificate is about to expire", "create the info@ mailbox on the new domain", "check the DNS records of this domain".

The external assistant does not log in with your credentials: it uses the LimePanel API with a token you create for it, carrying only the permissions you choose. You give it three things:

The specification describes every operation with its parameters and contains only the operations that token can use: the assistant does not have to guess anything.

Before you start#

• A LimePanel server reachable on port 8443 from the computer (or service) the assistant runs on, with a valid certificate.
• The tokens.manage permission on your account: if you do not see "API tokens and webhooks", ask whoever manages your account.
• An assistant that can make HTTP requests: one with terminal access (such as Claude Code) or an MCP client with a server that exposes an OpenAPI specification as tools.

1. Create a token with the minimum permissions#

1. In the panel open API tokens and webhooks (under Hosting, Reseller or Server, depending on your role; Ctrl+K finds it too).
2. New token.
3. Name: something that says who uses it, for example AI assistant – laptop. You will need it the day it has to be revoked.
4. Permissions: start from the "Read only" preset and remove what the assistant should not read. In particular, remove files.read unless you need it: it allows reading file contents, including configuration files with database passwords. Add a write permission (for example dns.manage or mail.manage) only when you really need it, one at a time.
5. Allowed networks: if the assistant runs on your computer or on a server with a fixed IP, enter that IP. From any other network the token is refused even if it is valid.
6. Lifetime in days: choose a short expiry, for example 30 days. If you leave it empty the token lasts 365 days; the maximum is 3650. Avoid "No expiry".
7. Create token and copy the value straight away: the panel keeps only a fingerprint and cannot show it again.

A token never has more permissions than the person who created it, and if you lose a permission, the token loses it too.

2. Copy the instructions for the assistant#

Still in API tokens and webhooks, the API guide button opens your panel's guide. In the section Using an AI assistant with the API you will find:

• the instructions for the assistant, already filled in with your panel's URL and your brand name: copy them into its system prompt (or the project instructions file);
• Specification filtered for you, the openapi.json file with only the operations your permissions allow.

The instructions tell the assistant to read the specification with its token first, to start with GET /me, to follow long operations to the end, to decide based on the error code and to ask for confirmation before any destructive operation.

3. Store the token safely#

The token belongs in an environment variable or a secrets manager, never in the chat, in an instructions file or in a repository. On your computer, in the terminal you will start the assistant from:

export LP_URL="https://panel.yourdomain.com:8443/api/v1"
export LP_TOKEN="lpt_…"   # the value you copied

# check: it must answer with your user and the token's permissions
curl -s -H "Authorization: Bearer $LP_TOKEN" "$LP_URL/me"

If you get an error, see Troubleshooting at the end of this page.

4. Connect your assistant#

Claude Code (or another assistant with a terminal)#

An assistant that runs commands in a terminal uses the API directly with curl: nothing else is needed.

1. Set LP_URL and LP_TOKEN as in step 3, in the same terminal.
2. In the folder you work in, save the instructions copied from the panel in the project instructions file (for Claude Code it is CLAUDE.md). The file contains the URL, not the token.
3. Start the assistant from that terminal and ask, for example: "Read the LimePanel specification and list my sites with their PHP version".
4. Before approving a command, look at it: it must use $LP_TOKEN, not the token written out in full.

Claude Desktop and other MCP clients#

LimePanel does not install an MCP server of its own: it exposes a REST API described by a standard OpenAPI specification. To use it from an MCP client (Claude Desktop or another) you use an MCP server that turns an OpenAPI specification into tools; several exist, including open-source ones. Whichever you choose, it needs the same three pieces of information:

In Claude Desktop, MCP servers are added from Settings → Developer → Edit Config, which opens claude_desktop_config.json. The entry looks like this; the command, arguments and variable names are the ones given in the documentation of the MCP server you chose:

{
  "mcpServers": {
    "limepanel": {
      "command": "<MCP server command>",
      "args": ["<arguments: specification and base URL>"],
      "env": {
        "LP_TOKEN": "lpt_…"
      }
    }
  }
}

Then restart Claude Desktop: the LimePanel tools appear among the available ones and Claude asks for your permission before using them. Add the instructions copied from the panel to the project or conversation instructions.

The configuration file contains the token: keep it on your computer only, do not sync it and do not share it.

Assistants that import an OpenAPI specification#

Some assistants let you create "actions" or "tools" by importing an OpenAPI specification. Import the openapi.json file downloaded from the API guide and choose API key authentication of type Bearer, with the token as the value.

Keep in mind that in this case requests come from the assistant provider's servers, not from your computer: the panel must be reachable from the internet on port 8443 and you cannot restrict the token to your IP. Make up for it with fewer permissions and a shorter expiry.

What the assistant can do, and what it cannot#

It can do, through the API, only what the token's permissions allow: read sites, DNS, mail, databases, certificates, backups and WordPress and, if you granted it, create or change things. Long operations (creating a domain, a backup, a restore) answer immediately and carry on in the background: the assistant follows them until they finish.

It cannot, not even with a token created by an administrator:

• use identity functions: passwords, sessions, two-step verification;
• act on behalf of another user;
• open the terminal;
• create other tokens;
• update the panel, manage the license or manage users.

These functions stay with a signed-in person with a second factor. In addition:

• it only sees the resources of your account (or of your customers, if you are a reseller): a resource of another customer answers as if it did not exist;
• restores and other irreversible operations require an explicit confirmation in the request;
• your package limits apply to it as well.

Security#

• Least privilege. A dedicated token for the assistant, read only, with write permissions added one at a time. Never a token with every permission in a third-party tool.
• One token per tool. If you revoke one, the others keep working, and the log tells you who did what.
• Networks and expiry. Restrict the token to the IP you work from and give it a short expiry. To rotate it: create the new one, swap it in, revoke the old one.
• Data leaves the server. Whatever the assistant reads through the API reaches the service that runs it. The panel's built-in assistant strips passwords, keys and personal data before sending anything; an external assistant gets no such clean-up. Do not grant files.read unless you need it.
• Confirm before it acts. Keep your assistant's permission prompts on and read every operation that changes data before approving it.
• Check what it does. API tokens and webhooks shows each token's last use and the IP it came from. In the audit log every action performed with a token carries the token's identifier.
• Revoke. Revoke on the token: it stops working from the next request. Do it at once if you think the token ended up in the wrong hands, or when you stop using the assistant.

Troubleshooting#

Every error has the same shape: error.code (stable, the one to look at), error.message and a request_id to quote to support.

Other common cases:

• No answer or connection refused. Port 8443 is not reachable from where the assistant runs: check the firewall. For assistants that work from the cloud, the panel must be reachable from the internet.
• Certificate error. The panel name does not point to the server yet and the panel uses a temporary certificate. Fix the DNS record: the Let's Encrypt certificate arrives by itself.
• The assistant makes up paths or fields. Have it read the specification with its token before starting: unknown fields are rejected.
• The downloaded specification lists operations the token cannot use. The API guide file is filtered on your permissions and the token may have fewer: the assistant should read the specification again from /api/v1/openapi.json with its own token.
• Messages in English or Italian. The X-LimePanel-Lang header (it or en) chooses the language of texts composed by the server; to decide what to do, always rely on error.code.