Documentation/Connecting/Your own panel/AI agent and MCP·9 / 9

AI agent and MCP

The panel connects to Claude Code, Cursor, VS Code and other AI agents over MCP: an operator asks in words — “who expires this week”, “what is with the de-fra node”, “extend those tagged vip” — and the agent goes to the same API with your token. The agent sees exactly what the token allows.

  1. Make a token

    With veli token add agent --rights read on the panel's server. Start with “Read only”: the agent can look and changes nothing.

  2. Connect the panel

    Once: over HTTPS — nothing to install, or with the veli command on a Linux computer. The token is in a file or in the agent's store, not in the chat.

  3. Ask

    The agent has ready scenarios: the morning round, what is with a node, a client's request, a clean-up of the inactive, the report after a move.

A token for the agent — read only
veli token add agent --rights read
Over HTTPS — a panel with a domain answers the agent itself, nothing to install
claude mcp add --transport http veli-panel https://panel.example.com/Zq7mT2xP4vLc9wRbE5nK/api/mcp --header "Authorization: Bearer $VELI_TOKEN"
With the veli command on your Linux computer (the token in the file ~/.veli/panel.token)
claude mcp add veli-panel -- veli panel mcp --url https://panel.example.com/Zq7mT2xP4vLc9wRbE5nK/api --token-file ~/.veli/panel.token
Read only
Clients, nodes, groups, events, traffic, the trash. No client's link in the answers.
Clients
Also: add, extend, change fields and tags, turn off and on, show a client's link, change many at once — a preview first, then the number.
All
Also: remove a client, a new link, restore from the trash, delete from the trash — and only with the name repeated. With the command — with the --destructive flag.
  • The agent changes things only with a “Clients” or “All” token and only if you turned on the --write flag. Over HTTPS the token itself sets the tools.
  • A client's link is a secret: ordinary answers do not have it, only client_link gives it, and over HTTPS that is a line in the log with the token's name. With the command there is no such line: where you need a trace, connect over HTTPS.
  • A client's name, note and contact are the client's text. The agent gets them as data and does not do what they say.

A prompt for an AI

A ready text that you paste into Claude or another AI assistant together with the API schema, and get a cabinet for your tasks.

  1. The token

    veli token add cabinet --rights clients. A storefront and reports are fine with read. Do not paste the token into the chat: only into your server's environment variables.

  2. The schema

    Download openapi.json and attach it to the talk with the AI — or give it the schema's address.

  3. The prompt

    Copy the text below, write your tasks in place of the line in brackets and send it together with the schema.

  4. Check

    Ask the AI how to run the cabinet at your place and try it on a test client. Then make sure that no link or token reached any log.

The token
veli token add cabinet --rights clients --days 90

VELI=https://panel.example.com/Zq7mT2xP4vLc9wRbE5nK/api
VELI_TOKEN=veli_…
curl -s "$VELI/openapi.json" \
  -H "Authorization: Bearer $VELI_TOKEN" -o veli-openapi.json
A prompt for Claude
Help me build a cabinet for my VPN service on the ready-made API of a Veli panel. The panel has no interface of its own in a browser: all the work goes through the HTTP API.

What you have:
- The API schema: the file openapi.json (attached). Take calls and fields only from it, invent nothing.
- The API address: https://panel.example.com/<secret path>/api (use mine).
- The token is in the environment variable VELI_TOKEN and goes in the Authorization: Bearer header. Never put the token in code, logs or site pages.

Rules:
1. Make every call that changes something with an Idempotency-Key header (the order's number): a system can send a notice twice, and the client must appear once.
2. A client's subscription link is a secret: show it only to that client and keep it out of logs.
3. The limit is 300 requests a minute per token. On 429, wait as many seconds as Retry-After says.
4. The token must never reach a client's browser: the cabinet calls the API from my server, not from a page.
5. Events (a client was added, a term is about to end, traffic is running out, a node went silent) arrive as webhooks. Check the HMAC-SHA256 signature from the veli-signature header, answer at once and do the work after.
6. Tie a client to my system through the external field (an order number or a user's ID in your system).

My tasks:
[WRITE THEM HERE: for example — an “Order” form creates a client for 30 days and shows the link and a QR code; a “My subscriptions” page by order number; a list of those who expire in 3 days with an “Extend” button; a summary of the nodes.]

First ask me questions if anything is missing. Then propose a plan, build the cabinet step by step and show how to run it locally and how to check it on a test client.