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:
- An MCP client that supports HTTP transport and OAuth (Cursor, Claude Desktop, Claude Code, and similar tools)
- 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
{
"mcpServers": {
"kloude": {
"url": "https://mcp.kloude.ir"
}
}
}
Claude Desktop
{
"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
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
{
"mcpServers": {
"kloude": {
"url": "https://mcp.kloude.ir"
}
}
}
Configuration file locations:
-
Cursor IDE:
- macOS/Linux:
~/.cursor/mcp.json - Windows:
%APPDATA%\Cursor\mcp.json
- macOS/Linux:
-
VS Code (Cody):
- macOS/Linux:
~/.config/Code/User/settings.json - Windows:
%APPDATA%\Code\User\settings.json
- macOS/Linux:
-
Windsurf:
- macOS/Linux:
~/.windsurf/mcp_config.json - Windows:
%APPDATA%\Windsurf\mcp_config.json
- macOS/Linux:
-
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:
{
"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
PROMPT: check my kloude servers list
Lists all servers in your Kloude account with their current status.
PROMPT: show details of server {server-name}
Displays detailed information about a specific server.
PROMPT: what clusters are running in my kloude account?
Shows all active clusters and their configurations.
Resource Queries
PROMPT: show my disk usage across all servers
Provides an overview of disk utilization.
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
- Confirm the config has only
"url": "https://mcp.kloude.ir"with no empty or wrong API key header. - Reload the MCP server in the client.
- Open
https://mcp.kloude.ir/.well-known/oauth-authorization-serverand confirm it listsregistration_endpointandauthorization_endpoint. - Ensure
https://mcp.kloude.iris 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
Related Resources
- API Reference - Direct API access for programmatic integration
- Settings - Manage API keys and organization access
- Getting Started - Initial setup and basic operations
- Security Best Practices - Account security guidelines
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