Connect Portainer to ChatGPT: Manage Kubernetes Clusters and Stacks

If you need to connect Portainer to ChatGPT to automate Kubernetes cluster management, orchestrate Docker Swarm stacks, or troubleshoot Edge jobs, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's tool calls and the Portainer API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. (If your team uses Claude, check out our guide on connecting Portainer to Claude or explore our broader architectural overview on connecting Portainer to AI Agents).

Giving a Large Language Model (LLM) read and write access to your container orchestration infrastructure is a complex engineering challenge. You have to handle hierarchical routing IDs, map massive Kubernetes schemas to MCP tool definitions, and deal with Portainer's specific proxy constraints. Every time an endpoint updates, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Portainer, connect it natively to ChatGPT, and execute complex DevOps workflows using natural language.

The Engineering Reality of the Portainer API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Portainer's API is painful. You aren't just integrating a single API - you are integrating a control plane that proxies requests to dozens of different underlying container environments (Kubernetes, Docker Swarm, Nomad, Edge Devices), all of which have different design patterns, error formats, and resource hierarchies.

If you decide to build a custom Portainer ChatGPT integration yourself, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with Portainer:

The Endpoint Routing Bottleneck

Portainer acts as a centralized proxy for multiple environments. Almost every API request requires an endpointId (sometimes referred to as kubernete_id or environment_id). An LLM cannot simply ask "list all pods." It must first query the endpoints list, parse the response to find the correct cluster ID based on string matching (e.g., finding the "production-k8s" environment), and then inject that endpointId into subsequent requests. If your MCP server does not expose these endpoints cleanly, the LLM will hallucinate cluster IDs and fail.

Divergent Schemas: Kubernetes vs. Edge

The payload structures for deploying a Kubernetes application are fundamentally different from deploying an Edge Stack or a standard Docker Compose file. Kubernetes endpoints require massive, deeply nested OpenAPI schemas (like K8sIngressController or v1beta1.PodMetricsList). Edge computing endpoints rely on Portainer-specific concepts like EdgeGroups and EdgeJobs with offline synchronization constraints. Your MCP server must accurately map these disparate schemas into JSON Schema for ChatGPT to understand what arguments to pass.

Strict Rate Limiting and 429 Errors

When interacting with Portainer - especially when querying metrics across hundreds of nodes or pulling large logs - you will hit rate limits imposed either by Portainer itself or the underlying Kubernetes API server. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The AI agent (the caller) is completely responsible for implementing its own exponential backoff logic.

How to Generate a Managed MCP Server for Portainer

Instead of building a JSON-RPC 2.0 server from scratch, handling token hashing, and mapping Portainer's schemas manually, you can use Truto to generate an MCP server dynamically. Truto derives tool definitions directly from the integration's documented endpoints.

You can generate the MCP server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For administrators who need to quickly generate a server URL for local testing or ChatGPT desktop:

1. Log into your Truto account and navigate to the Integrated Accounts page for your Portainer connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure the server (set a name, select allowed methods like "read" or "write", and optionally set an expiration date).
5. Click Save and copy the generated MCP server URL.

Method 2: Via the Truto API

For developer platforms and internal tools that need to provision MCP servers dynamically, use the REST API. This endpoint validates the configuration, hashes the token securely, and returns a ready-to-use JSON-RPC endpoint.

Request:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portainer K8s Management MCP",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

Response:

{
  "id": "mcp_token_abc123",
  "name": "Portainer K8s Management MCP",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67g8h9i0j"
}

The returned url is fully self-contained. It encodes the cryptographic token linking the server to that specific Portainer integrated account.

How to Connect the MCP Server to ChatGPT

Once you have the Truto MCP URL, connecting it to ChatGPT takes seconds. You can do this either through the ChatGPT interface or via a manual configuration file for local/custom agents.

Method 1: Via the ChatGPT UI

To connect the server directly to your ChatGPT Plus/Enterprise workspace:

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Toggle Developer mode on (custom MCP connectors require this flag).
3. Under the MCP servers / Custom connectors section, click Add a new server.
4. Name: Enter a descriptive name (e.g., "Portainer Automation").
5. Server URL: Paste the Truto MCP URL (https://api.truto.one/mcp/...).
6. Click Save. ChatGPT will immediately perform a handshake with the server, request the tools/list, and make the Portainer operations available in your chat context.

Method 2: Via Manual Configuration File (CLI/Cursor/Custom Agents)

If you are running local agents or using IDEs like Cursor, you can connect to the remote Truto MCP server using the official Server-Sent Events (SSE) transport adapter provided by Anthropic.

Create or update your mcp.json (or claude_desktop_config.json) file:

{
  "mcpServers": {
    "portainer-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/a1b2c3d4e5f67g8h9i0j"
      ]
    }
  }
}

This configuration instructs the local MCP client to proxy tool calls over SSE to the remote Truto endpoint, allowing your local agents to securely interact with your Portainer cluster.

Core Portainer Tools for AI Agents

When the LLM connects to the MCP server, it receives a curated list of tools. Here are the highest-leverage operations your AI agent can execute to manage Kubernetes clusters and stacks.

1. List All Portainer Endpoints

This tool retrieves all environments (endpoints) managed by Portainer. It is the critical first step in almost any workflow, as the LLM needs the Id of the environment to interact with specific clusters.

"Fetch a list of all environments in Portainer. Find the endpoint ID for the cluster named 'prod-us-east-k8s' so we can query its metrics."

2. List Kubernetes Nodes and Limits

This tool (list_all_portainer_kubernete_nodes_limits) retrieves the CPU and memory limits of all nodes within a specific Kubernetes cluster. It is essential for capacity planning and troubleshooting resource exhaustion.

"Check the CPU and memory limits across all nodes in endpoint ID 4. Are any of the nodes maxed out on memory allocations?"

3. Deploy a Kubernetes Stack from a Git Repository

This tool (create_a_portainer_kubernetes_repository) triggers a GitOps workflow, deploying a new Kubernetes stack directly from a git repository into a specified environment.

"Deploy a new Kubernetes stack to endpoint ID 2 using the main branch of our frontend-app repository. Name the stack 'frontend-v2'."

4. Fetch Live Pod Metrics

This tool (list_all_portainer_metrics_pods) retrieves live metrics for pods within a specific Kubernetes namespace. It uses the underlying metrics-server API to return CPU and memory usage.

"Get the live metrics for all pods in the 'default' namespace on endpoint ID 3. Let me know if any pod is consuming more than 500m CPU."

5. Attach to Edge Job Logs

This tool (portainer_edge_jobs_attach_log) collects and updates the logs from a Portainer Edge Job running on a specific environment. It is invaluable for diagnosing failed background tasks on edge devices.

"Fetch the latest logs for edge job ID 12 running on endpoint ID 7. Summarize any error traces you find in the output."

6. Migrate a Docker Swarm Stack

This tool (create_a_portainer_stack_migrate) migrates a Portainer stack from one environment to another, safely re-creating it in the target before removing the original.

"Migrate the stack named 'redis-cache' (Stack ID 8) to the new failover environment (Endpoint ID 5). Confirm when the migration completes successfully."

7. Audit GitOps Workflows

This tool (list_all_portainer_gitops_workflows) lists all GitOps workflows across all environments, allowing the LLM to audit sync statuses and identify paused or failing deployments.

"List all GitOps workflows currently managed by Portainer. Identify any workflows that are currently in an 'error' or 'paused' state and tell me which environment they belong to."

For a complete list of available operations, including user administration, RBAC controls, and Helm chart deployments, view the complete tool inventory on the Portainer integration page.

Workflows in Action

Exposing individual endpoints as tools is helpful, but the real power of an MCP server emerges when an LLM orchestrates multi-step workflows. Here are two real-world scenarios showing how ChatGPT leverages the Portainer MCP server.

Scenario 1: Kubernetes Capacity Audit and GitOps Deployment

A DevOps engineer asks ChatGPT to verify cluster capacity before rolling out a new microservice.

"Check our 'prod-cluster' to see if we have enough spare CPU capacity across the nodes. If things look healthy, deploy the 'payment-service' stack from our Git repository."

How the AI Agent executes this:

1. list_all_portainer_endpoints: The LLM queries the endpoint list to map the string "prod-cluster" to its internal Id (e.g., ID 4).
2. list_all_portainer_kubernete_nodes_limits: The LLM calls this tool using kubernete_id=4 to retrieve the CPU and memory limits across all nodes.
3. list_all_portainer_metrics_pods: The LLM analyzes live usage against the limits to ensure there is buffer capacity.
4. create_a_portainer_kubernetes_repository: Having confirmed capacity, the LLM constructs the deployment payload and triggers the GitOps stack creation on Endpoint 4.

The engineer receives a concise confirmation that the cluster had 40% spare CPU capacity and that the Git deployment has been successfully initiated.

sequenceDiagram
participant User as User
participant ChatGPT as ChatGPT
participant Truto as Truto MCP Server
participant Portainer as Portainer API

User->>ChatGPT: Deploy payment-service if capacity allows
ChatGPT->>Truto: Call list_all_portainer_endpoints
Truto->>Portainer: GET /endpoints
Portainer-->>Truto: Return endpoints list
Truto-->>ChatGPT: Return Endpoint ID (4)
ChatGPT->>Truto: Call list_all_portainer_kubernete_nodes_limits (id=4)
Truto->>Portainer: GET /kubernetes/4/nodes/limits
Portainer-->>Truto: Return node capacities
Truto-->>ChatGPT: Return capacity data
ChatGPT->>Truto: Call create_a_portainer_kubernetes_repository (id=4, git_url)
Truto->>Portainer: POST /kubernetes/4/stacks
Portainer-->>Truto: Stack created successfully
Truto-->>ChatGPT: Return deployment ID
ChatGPT-->>User: Capacity confirmed. Deployment initiated.

Scenario 2: Troubleshooting Failing Edge Jobs

An IT administrator needs to figure out why an automated backup script failing across edge devices.

"Find the edge job for 'nightly-backups'. Get the logs for any failed tasks related to that job on the 'retail-store-01' environment and summarize the errors."

How the AI Agent executes this:

1. list_all_portainer_edge_jobs: The LLM fetches all edge jobs to find the id for "nightly-backups" (e.g., Job ID 15).
2. list_all_portainer_endpoints: The LLM looks up the endpoint ID for "retail-store-01" (e.g., Endpoint 9).
3. list_all_portainer_edge_job_tasks: The LLM queries the tasks for Job 15 to find the specific task ID associated with Endpoint 9.
4. portainer_edge_job_tasks_attach_log: The LLM triggers the log collection for that specific task.
5. portainer_edge_job_tasks_list_logs: The LLM pulls the file content, parses the stack trace, and extracts the core failure reason.

The admin gets a natural language summary of the exact bash script error (e.g., "Disk full on partition /mnt/data") without ever having to SSH into the edge device or dig through the Portainer UI.

Security and Access Control

When you give an LLM access to your container orchestration platform, security is non-negotiable. Portainer controls critical infrastructure. Truto's managed MCP servers provide granular controls to limit the blast radius of AI agents:

• Method Filtering: You can restrict a server to safe operations. Setting config.methods: ["read"] ensures the LLM can only query logs, metrics, and configurations, preventing it from accidentally deleting a stack or scaling down a deployment.
• Tag Filtering: You can group tools by domain. If you only want an agent to handle user administration, you can filter tools using config.tags: ["users", "teams"], completely hiding Kubernetes deployment operations from the model.
• Time-to-Live (TTL): You can set an expires_at timestamp when creating the server. Behind the scenes, Truto schedules a cleanup alarm that automatically deletes the token and purges it from KV storage at the exact minute it expires. This is perfect for granting temporary debugging access.

Ship Automation Faster with Managed MCP

Connecting Portainer to ChatGPT unlocks incredible operational velocity. Instead of writing bash scripts to parse logs or navigating complex UIs to check node capacity, your team can interact with your infrastructure conversationally.

Building this integration manually requires deep knowledge of the Model Context Protocol, constant schema maintenance for Kubernetes resources, and complex handling of Portainer's proxy architecture. Truto handles this entire infrastructure layer for you. By deriving tools directly from API documentation and mapping requests dynamically, Truto allows you to generate a secure, production-ready MCP server in seconds.