MCP server

Where in the portal: API reference › Tools (https://<your-domain>/apidoc) shows the endpoint and client snippets; keys are created at API keys (/api-keys). There is no setting in the admin: the endpoint is part of the panel.

What it does

The Model Context Protocol (MCP) lets an AI assistant call tools. NexCMP serves an MCP endpoint at https://<your-domain>/mcp. Every public API operation becomes one tool (vm_list, vm_start, billing_wallet, ...), so a customer can ask their assistant "which of my VMs are running?" or "stop the staging VM". The assistant acts with the customer's own API key and permissions only.

Configuring NexCMP itself with AI?

This page is the customer MCP endpoint (/mcp). To let an AI assistant configure your own panel as an administrator, see Configure with AI (endpoint /mcp/admin, admin keys ak_).

Requirements

Item	Requirement
Server	Nothing to install: the endpoint is served by the panel and reachable wherever the panel is. Your reverse proxy must forward /mcp to the panel.
Customer	An API key (vk_...) with the scopes the assistant needs.
Client	An MCP client that supports the Streamable HTTP transport and a custom Authorization header: Claude Code, Claude Desktop (through the mcp-remote bridge), Cursor, VS Code with Copilot agent mode and similar.
Protocol versions	2025-11-25, 2025-06-18 and 2025-03-26.

Prepare the infrastructure

Nothing, beyond making sure https://<your-domain>/mcp is not blocked by a firewall or a proxy rule. A browser-based MCP client from another origin is refused unless that origin is allowed; command-line and desktop clients send no Origin header and work as they are.

Connect (customer side)

1. Create an API key in the portal (API keys › Create key) with only the scopes you want the assistant to use, a short expiry and, if possible, an IP restriction.

2. Add the server to your client. Replace cloud.example.com and the key.

   Claude Code

   claude mcp add --transport http cloud https://cloud.example.com/mcp \
     --header "Authorization: Bearer vk_XXXX"

   Cursor (~/.cursor/mcp.json or .cursor/mcp.json; set CLOUD_API_KEY in the environment Cursor starts from):

   {
     "mcpServers": {
       "cloud": {
         "url": "https://cloud.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
       }
     }
   }

   Claude Desktop (needs Node.js 18+; claude_desktop_config.json), through the mcp-remote bridge:

   {
     "mcpServers": {
       "cloud": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
         "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
       }
     }
   }

   Write the header without a space after the colon and put the whole value in the environment variable, as above.

3. Restart the client and ask it to list your tools.

Check the connection without a client:

curl -s https://cloud.example.com/mcp \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

How it works

Item	Detail
Endpoint	POST /mcp with a JSON-RPC 2.0 message; the answer is application/json. GET /mcp answers 405 (no server-to-client stream); DELETE /mcp ends the session.
Authentication	Only Authorization: Bearer vk_... (session tokens, cookies and admin keys are refused with 401 and a WWW-Authenticate: Bearer header).
Session	Mcp-Session-Id is issued by initialize, bound to that key, valid 24 hours; at most 16 sessions per key.
Tools	One per public API operation visible to the key. The tool name is the CLI command with _ instead of spaces and dashes (vm firewall add becomes vm_firewall_add) and equals the OpenAPI operationId. A tool is listed only when the key has its scope and the module is enabled.
Capabilities	Tools only (no resources or prompts).
Size	Request body up to 1 MB; tool result text up to about 100 KB (the rest is cut with a note); a call takes at most 55 seconds.

Safety rules

• Same gate as REST. Each tools/call goes through the panel's own request pipeline: scope, site, IP restriction, rate limit, idempotency, ownership checks (404 for other people's resources) and quotas all apply. MCP cannot grant anything the key does not have.
• Confirmation. Tools that cost money, delete, or return credentials (console tickets, kubeconfig, S3 or SSH secrets, password resets, new keys) require the argument confirm: true. The tool description tells the assistant to pass it only after the user has approved, so an instruction hidden in a web page or log cannot trigger it on its own.
• Idempotency. Paid tools accept idempotency_key; if omitted a stable key is derived from the tool name and arguments, so an identical retry cannot charge twice.
• Not exposed as tools: streaming endpoints (the AI Agent chat), one-time SSH or console WebSocket tickets, binary downloads, and the VPN app endpoints (/v1/ext/*).
• Never possible: the API never allows top-ups, password changes, deleting the account or creating keys, so no assistant can do them.

Limits

Limit	Default
Tool calls per key	60 per minute
MCP requests per key	240 per minute
Plus the normal key and account limits	See REST API

Over the limit the endpoint answers HTTP 429 with a JSON-RPC error and Retry-After.

Verify

1. The curl command above returns a JSON-RPC result with a tools list. Only tools matching the key's scopes appear.
2. In your client ask "list my VMs": the assistant calls vm_list and shows the result.
3. In the portal the key's Last used time moves, and write calls appear in the Key usage log.

Limits & notes

• Browser sign-in (OAuth). The reference page also describes signing in through the browser for clients that support MCP OAuth. In an installed NexCMP the supported, tested method is the API key (or cmp login for the CLI).
• Reseller sites do not show the MCP section; their customers use the reseller's domain for the API.
• Least privilege. Create a dedicated key per assistant with read scopes first; add write scopes only when needed.
• Revoke the key in API keys to cut the assistant's access at once.

Troubleshooting

Symptom	Cause	Fix
401 with WWW-Authenticate: Bearer	No key, wrong key, or a session token	Send Authorization: Bearer vk_....
403 about Origin	A browser page on another origin	Use a desktop or CLI client; or ask your administrator to allow the origin (mcp_allowed_origins).
404 on a request with Mcp-Session-Id	Session belongs to another key or expired	Run initialize again.
405 on GET /mcp	Expected: the server has no event stream	Use POST only (clients do this automatically).
The tool list is short	Key scopes or modules	Add scopes to the key; enable the module.
Tool answers it needs confirm: true	Paid, delete or sensitive tool	The assistant must set confirm after you approve.
429	MCP or key rate limit	Wait for Retry-After.
Client cannot connect with a header	Client without custom-header support	Use the mcp-remote bridge.