MCP Server Setup

Setup Qovery AI Copilot with Claude Desktop using the Model Context Protocol

Overview

The Qovery MCP (Model Context Protocol) Server enables you to use Qovery AI Copilot directly in any MCP-compatible client, including ChatGPT, Claude, and Claude Code. This gives you natural language control over your entire Qovery infrastructure.

Activation Required: Before using the MCP Server, organization administrators must first activate Qovery AI Copilot from the console settings. See the Getting Started guide for activation instructions.

What is MCP? The Model Context Protocol is an open standard developed by Anthropic that allows AI assistants to interact with external tools and systems. Learn more →

Operating Modes

By default, the MCP Server operates in read-only mode. To enable read-write access, you must explicitly opt in using a URL parameter and have the necessary permissions configured.

Read-Only Mode (Default)

Safe exploration - View-only access

In read-only mode, the Copilot allows you to:

• View information and status
• Get help and recommendations
• Troubleshoot issues
• Monitor deployments
• Analyze infrastructure
• No changes to infrastructure

This is the default mode, ensuring safe exploration without risk of accidental modifications.

Read-Write Mode

Full automation - Maximum capabilities

In read-write mode, the Copilot can perform complete automation:

• Deploy applications and services
• Create new environments and resources
• Update configurations and settings
• Add/modify/delete environment variables
• Scale, restart, or stop services
• Delete resources (with confirmation)
• Execute complex workflows

The Copilot will ask for confirmation before performing destructive operations like deletions.

Read-write mode requires both:

1. AI write permissions enabled in your organization settings
2. An API token with sufficient permissions (Developer or Admin role)
3. Adding read_write=true to the MCP Server URL

Permission Hierarchy: The MCP Server is read-only by default. To enable read-write access, you must:

• Add read_write=true to the MCP Server URL
• Have AI write permissions enabled in your organization settings
• Use an API token with sufficient role permissions

The most restrictive setting takes precedence. For example, if you add read_write=true but your token has viewer permissions, the Copilot will remain in read-only mode.

Prerequisites

Before using the MCP Server:

• MCP-Compatible Client: Any MCP-compatible application (tested with ChatGPT, Claude, and Claude Code)
• Qovery Account: Active account with infrastructure
• API Token: Generate from Qovery Console (Settings → API Tokens)

Setup

1. Generate Your Qovery API Token

1. Open Qovery Console

   Go to console.qovery.com

2. Navigate to Settings

   Click on the settings icon in your organization

3. Access API Tokens

   Go to API Tokens section

4. Generate Token

   Click “Generate Token” and copy it

   Save this token securely. You won’t be able to see it again!

2. Configure Your MCP Client

The Qovery MCP Server is accessible via the following URL:

https://mcp-api-ai.qovery.com/mcp

You can optionally include your API token and operating mode as query parameters:

https://mcp-api-ai.qovery.com/mcp?token=<your-token>

To enable read-write mode (requires appropriate permissions):

https://mcp-api-ai.qovery.com/mcp?token=<your-token>&read_write=true

Token in URL: If you provide the token in the URL, you won’t be prompted for authentication during the session. If omitted, the token will be requested when you first interact with the server.

Operating Mode: By default, the MCP Server operates in read-only mode. To enable read-write access, add read_write=true to the URL. This requires AI write permissions to be enabled in your organization settings and a token with sufficient permissions.

Add the Qovery MCP Server to your MCP client’s configuration using:

Server URL: https://mcp-api-ai.qovery.com/mcp

Refer to your specific MCP client’s documentation for detailed setup instructions on how to add a custom MCP server.

The Qovery MCP Server is also available through the MCP Registry.

Usage

Authentication with API Token

The Qovery MCP Server supports 3 authentication methods:

1. Query Parameter

Add your token directly to the MCP Server URL:

https://mcp-api-ai.qovery.com/mcp?token=your_qovery_token

To force read-only mode:

https://mcp-api-ai.qovery.com/mcp?token=your_qovery_token&read-only=true

2. Custom Header

Add the X-Qovery-Token header to your requests:

X-Qovery-Token: your_qovery_token

To force read-only mode, add read-only=true as a query parameter:

https://mcp-api-ai.qovery.com/mcp?read-only=true

3. Authorization Header

Use the standard Authorization header:

Authorization: Token your_qovery_token

To force read-only mode, add read-only=true as a query parameter:

https://mcp-api-ai.qovery.com/mcp?read-only=true

Usage Examples

Once authenticated, you can interact with your infrastructure naturally:

Check Status

"Show me all my environments"
"What's the status of production?"
"List applications in the staging environment"

Deploy Applications

"Deploy the latest version of my-api to production"
"Restart the frontend application"
"Scale the API service to 5 replicas"

Troubleshoot Issues

"Why is my deployment failing?"
"Show me error logs from the last hour"
"Debug the connection timeout in staging"

Manage Infrastructure

"Create a new environment called feature-test"
"Clone production to staging"
"Stop all services in the dev environment"

Troubleshooting

MCP Server Not Connecting

Issue: Client doesn’t show Qovery tools or cannot connect

Solutions:

1. Verify the MCP Server URL is correct: https://mcp-api-ai.qovery.com/mcp
2. Check your internet connection
3. Restart your MCP client
4. Contact Qovery Support if the issue persists

Authentication Errors

Issue: “Authentication failed” or “Invalid token” errors

Solutions:

1. Verify your API token is correct (check for copy-paste errors)
2. Ensure the token hasn’t been revoked or expired
3. Verify the token has the necessary permissions for the requested operation
4. Generate a new API token if needed from Qovery Console

Token Not Persisting

Issue: Need to re-enter token for each question

Solutions:

1. Ensure you’re staying in the same conversation
2. Provide the token at the beginning of new conversations
3. Check if your client is maintaining the conversation context

Security Best Practices

API Token Security:

• Never share your API tokens publicly
• Don’t commit tokens to version control
• Revoke tokens you no longer need from Qovery Console
• Use tokens with the minimum required permissions
• Rotate tokens regularly

Token Permissions

The API token has the same permissions as the role you selected during creation:

• Can only access resources within your organization
• Respects organization RBAC policies
• All actions are audited in Qovery Console

Next Steps

Console Copilot

Use the built-in Console Copilot for quick help

Slack Bot

Set up the Slack Bot for team collaboration

View Capabilities

Explore everything Copilot can do

Common Tasks

Practical examples and use cases

Resources

• MCP Protocol: modelcontextprotocol.io
• Claude Desktop: claude.ai/download
• Technical Blog: How We Built an Agentic DevOps Copilot