kloudedocs
Browse documentation
On this page

PRODUCT GUIDE

Kloude MCP Server

Connect to Kloude infrastructure using the Model Context Protocol (MCP) server. Manage servers, clusters, and resources directly from Claude Desktop or other MCP clients.

The Kloude MCP Server enables seamless integration between Claude Desktop and your Kloude infrastructure. Using the Model Context Protocol (MCP), you can manage servers, query resources, and execute operations directly through natural language conversations with Claude.

What is MCP?

Model Context Protocol (MCP) is an open protocol that allows AI assistants like Claude to securely connect to external data sources and tools. By connecting Claude Desktop to the Kloude MCP server, you can:

  • Query your Kloude servers and resources
  • Check cluster status and configurations
  • Manage infrastructure through natural language
  • Automate common operations without leaving your conversation

Prerequisites

Before connecting, ensure you have:

  1. An MCP client that supports HTTP transport and OAuth (Cursor, Claude Desktop, Claude Code, and similar tools)
  2. A Kloude account you can sign in to on the panel

The first approval is read-only (Ask) for the organization you select. Allow Change only when you want that client to reboot, delete, or apply changes. The token stays on that organization. Terraform and CI still use an API key from Settings → API keys. Opening the MCP address itself in a browser sends you to panel login.

Configuration

Add the MCP URL only. Do not put an API key in the MCP config for interactive clients.

Cursor

json
{ "mcpServers": { "kloude": { "url": "https://mcp.kloude.ir" } } }

Claude Desktop

json
{ "mcpServers": { "kloude": { "url": "https://mcp.kloude.ir" } } }

Claude Desktop file locations:

  • macOS: ~/.claude/settings.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.claude/settings.json

Claude Code CLI

bash
claude mcp add --transport http kloude https://mcp.kloude.ir claude mcp list

The CLI registers itself with the MCP host, opens the panel for approval, then stores the token.

Universal Configuration for All AI Agents

json
{ "mcpServers": { "kloude": { "url": "https://mcp.kloude.ir" } } }

Configuration file locations:

  • Cursor IDE:

    • macOS/Linux: ~/.cursor/mcp.json
    • Windows: %APPDATA%\Cursor\mcp.json
  • VS Code (Cody):

    • macOS/Linux: ~/.config/Code/User/settings.json
    • Windows: %APPDATA%\Code\User\settings.json
  • Windsurf:

    • macOS/Linux: ~/.windsurf/mcp_config.json
    • Windows: %APPDATA%\Windsurf\mcp_config.json
  • Other AI Agents: Check your tool's documentation for MCP configuration file location.

Setup Guide

Add the MCP URL

Put https://mcp.kloude.ir in your client config (examples above). Do not add an X-API-KEY header for interactive use.

Connect the server

Restart or reload the client so it loads the MCP server. The client discovers OAuth metadata and opens the panel approval page.

Sign in and approve

Sign in to Kloude if needed, pick the organization, leave Ask selected unless you need Change, then click Allow.

Return to the client

The browser returns to the client. Connected apps under Settings → API keys lists the approval. You can disconnect it there later.

Verify

Ask something like "check my kloude servers list". The tools run as the organization you approved.

Automation (API key)

Terraform, scripts, and CI keep using an API key from Settings → API keys:

json
{ "mcpServers": { "kloude": { "url": "https://mcp.kloude.ir", "headers": { "X-API-KEY": "{YOUR_API_KEY}" } } } }

That key stays on the organization chosen when you created it.

Usage Examples

Once configured, you can interact with your Kloude infrastructure using natural language. Here are some example prompts:

Server Management

text
PROMPT: check my kloude servers list

Lists all servers in your Kloude account with their current status.

text
PROMPT: show details of server {server-name}

Displays detailed information about a specific server.

text
PROMPT: what clusters are running in my kloude account?

Shows all active clusters and their configurations.

Resource Queries

text
PROMPT: show my disk usage across all servers

Provides an overview of disk utilization.

text
PROMPT: list all networking resources

Displays VPCs, subnets, and networking configurations.

Available Operations

The Kloude MCP server provides access to the following resources:

  • Servers: List, query, and manage virtual machines
  • Clusters: View and manage Kubernetes clusters
  • Disks: Check storage volumes and usage
  • Networking: Query VPCs, subnets, and firewall rules
  • Monitoring: Access metrics and resource utilization
  • Registry: Query container registry images

Troubleshooting

The client never opens the login page

  1. Confirm the config has only "url": "https://mcp.kloude.ir" with no empty or wrong API key header.
  2. Reload the MCP server in the client.
  3. Open https://mcp.kloude.ir/.well-known/oauth-authorization-server and confirm it lists registration_endpoint and authorization_endpoint.
  4. Ensure https://mcp.kloude.ir is reachable from your network.

Authentication Errors

  • Finish the panel approval and return to the client after Allow.
  • Check Connected apps under Settings → API keys; disconnect and connect again if the token was revoked.
  • For automation configs, confirm the API key is valid and still present.

No Response from MCP Server

  • Ensure you have resources in the organization you approved.
  • Ask-only approvals cannot reboot or delete; approve Change if you need those tools.
  • Try a simple query like "check my kloude servers list" first.

Security Best Practices

  • Never commit configuration files with API keys to version control
  • Rotate keys regularly from the Settings panel
  • Use least privilege: Create separate API keys for different use cases
  • Revoke immediately if a key is compromised
  • Store securely: Keep configuration files with appropriate file permissions

Support

Need help with the MCP server? Visit our Support page or contact the Kloude team for assistance with:

  • MCP server configuration
  • Panel approval and connected apps
  • Integration troubleshooting
  • Feature requests