Skip to content

Connect an AI assistant or automation tool (Pro)

What it's for

The Management API is both a plain REST API and an MCP server — the same API token lets you connect an AI assistant that operates your fleet through natural-language requests, or wire a workflow tool like n8n straight into specific endpoints. Same token, same scopes, same audit trail either way — see API tokens first if you haven't minted one.

Two ways to connect, pick whichever fits:

  • MCP — the assistant discovers and calls tools itself ("which clients haven't checked in this week", "kill client 42's tunnel"). Endpoint: https://<your-backend>/api/mgmt/v1/mcp.
  • Plain REST — you (or a workflow tool) call specific endpoints directly. Base path: https://<your-backend>/api/mgmt/v1/, same bearer token, works with literally anything that can make an HTTP request. Full endpoint list: Admin → API Reference.

Every option below uses the token as Authorization: Bearer vlnm_... — no separate credential, no OAuth flow, no per-tool signup.

Claude Code

The most direct path — one command:

claude mcp add --transport http valenius https://your-backend/api/mgmt/v1/mcp \
  --header "Authorization: Bearer vlnm_..."

Verify with claude mcp list, then just ask it something.

Claude Desktop

Desktop's built-in remote-connector flow (Settings → Connectors → Add custom connector) expects OAuth/form-based sign-in, not a static token typed into a config file — pasting the server URL there will prompt for an authentication step that doesn't match how this server's tokens work. Use Claude Code instead for this kind of server.

Gemini CLI

Add an entry to your MCP settings file (typically ~/.gemini/settings.json):

{
  "mcpServers": {
    "valenius": {
      "httpUrl": "https://your-backend/api/mgmt/v1/mcp",
      "headers": {
        "Authorization": "Bearer vlnm_..."
      }
    }
  }
}

Gemini CLI expands $VAR/${VAR} in header values if you'd rather keep the token in an environment variable than the file itself.

OpenAI

Via the Responses API, pass the server as an mcp-type tool:

{
  "model": "gpt-4.1",
  "tools": [
    {
      "type": "mcp",
      "server_label": "valenius",
      "server_url": "https://your-backend/api/mgmt/v1/mcp",
      "headers": {
        "Authorization": "Bearer vlnm_..."
      },
      "require_approval": "never"
    }
  ],
  "input": "Which clients haven't checked in this week?"
}

allowed_tools (an array of tool names) is optional if you want to restrict which MCP tools this particular call can see, on top of whatever the token's scopes already restrict server-side.

The consumer ChatGPT app's Connectors feature is built around OAuth sign-in rather than a static token, so for a vlnm_ token the developer API above is the path that actually works today.

Mistral

Register the server as a Connector via the Mistral SDK or REST API:

from mistralai import Mistral

client = Mistral(api_key="your-mistral-api-key")
connector = client.beta.connectors.create(
    name="valenius",
    description="Valenius fleet management",
    server="https://your-backend/api/mgmt/v1/mcp",
    visibility="private",
    headers={"Authorization": "Bearer vlnm_..."},
)

Equivalent raw call: POST https://api.mistral.ai/v1/beta/connectors with the same fields. name must be 64 characters or fewer, letters/digits/underscore/dash only. Once registered, reference the connector from your Mistral agent the same way you'd reference any other tool.

n8n

Use the MCP Client Tool node (search "MCP Client Tool" when adding a node to an AI Agent workflow):

  • Endpoint: https://your-backend/api/mgmt/v1/mcp
  • Authentication: choose Bearer and paste the token — n8n also supports Header Auth/Multiple Headers Auth credential types if you'd rather store it as a named credential than inline.
  • Transport: set to HTTP Streamable.

!!! warning "Known n8n bug — set transport via Expression mode" As of current n8n releases, the transport dropdown can silently keep using the older SSE transport even when "HTTP Streamable" is selected (n8n-io/n8n#24967) — which won't work against this server. Workaround: switch the transport field to Expression mode (the little "fx" toggle next to it) and enter the literal value httpStreamable instead of picking it from the dropdown.

If you just want a workflow step to call one specific endpoint (e.g. a scheduled "check for offline clients" workflow) rather than give an AI agent open-ended tool access, skip MCP entirely and use n8n's generic HTTP Request node instead — set the URL to a REST endpoint under /api/mgmt/v1/**, method to match, and authentication to Header Auth with Authorization: Bearer vlnm_.... This works the same way for any tool that can make an HTTP request, not just n8n.

Calling the REST API directly

Every option above is a wrapper around the same REST API — nothing stops you calling it straight from a script or any tool not listed here:

curl -H "Authorization: Bearer vlnm_..." \
  https://your-backend/api/mgmt/v1/clients?status=active

Full endpoint reference: Admin → API Reference (generated live from the running server, so it always matches what's actually deployed).

Pitfalls

  • A token is a credential, not a person. Everything it does — REST call or MCP tool call — is logged under the token's name, not under whoever triggered it. If several people or workflows share one token, the audit log can't tell them apart; mint one token per person/workflow if that distinction matters to you.
  • Start read-only. Grant clients:actions or a *:write scope only once you're comfortable letting the integration act, not just look.
  • configs:read is the one scope that can see a WireGuard private key. Think twice before handing it to an AI assistant specifically — the config then transits that assistant's own infrastructure, not just your backend.
  • Revoking a token takes effect immediately — every integration using it (MCP or REST) stops working on its very next call.