Skip to main content

MCP (Model Context Protocol)

What is MCP?​

The Model Context Protocol (MCP) is an open standard that enables AI assistants like Cursor to securely interact with your Quave Cloud infrastructure. Think of it as giving your AI assistant controlled access to manage your applications - it can check logs, deploy updates, scale containers, and more, all through natural conversation in your IDE.

Example: Instead of logging into the Quave Cloud dashboard, you can ask Cursor:

  • "Show me the recent errors in my production app"
  • "Deploy the latest commit to staging"
  • "Scale my web containers to 5 replicas"

MCP was created by Anthropic and follows modern security best practices to ensure your resources remain protected.

How It Works​

┌─────────────┐         ┌──────────────┐         ┌─────────────────┐
│   You ask   │         │     MCP      │         │  Quave Cloud    │
│   Cursor    │ ───────>│    Server    │ ───────>│      API        │
│   in IDE    │         │   (Secure)   │         │                 │
└─────────────┘         └──────────────┘         └─────────────────┘
      ↓                         ↓                          ↓
 Natural                   Validates                   Executes
 Language                  Permissions                  Safely
  1. You communicate with Cursor in natural language from your IDE
  2. Cursor translates your request into MCP tool calls
  3. MCP Server validates your permissions and security settings
  4. Quave Cloud API executes the approved operations
  5. Results are returned to Cursor, who explains them to you

Important: What's Enforced Where​

Understanding what the Quave Cloud server enforces vs what the MCP client respects is crucial for security:

SettingEnforced ByCan be bypassed?Description
Enabled Scopes✅ Server❌ NoThe server validates every request against your enabled scopes. Cannot be bypassed.
MCP Key Enabled✅ Server❌ NoDisabled keys are rejected at the server level. Cannot be bypassed.
Security Level⚠️ MCP Client✅ Yes (client dependent)Controls confirmation prompts in your AI client. Different clients may implement this differently.
Session Duration⚠️ MCP Client✅ Yes (client dependent)How long approvals last. Managed by the client, not the server.

What this means for you:

  • ✅ Server-enforced settings (Enabled Scopes, Key Status) provide true security - even if someone modifies the MCP client, these protections remain
  • ⚠️ Client-enforced settings (Security Level, Session Duration) are convenience features that improve UX but don't provide security guarantees - they depend on the MCP client's implementation

Security Best Practice: Only enable the scopes you truly need. The server will block any operation outside your enabled scopes, regardless of how the MCP client is configured.

Getting Started​

Step 1: Create an MCP Key​

  1. Log into Quave Cloud
  2. Go to User Menu → MCP
  3. Click Create MCP Key
  4. Configure your key:
    • Name (required): A memorable identifier like my-laptop, cursor-ide, or work-macbook
    • Enabled Scopes: Choose which operations this key can perform (see below)
    • Security Level: How strict the confirmation prompts should be
    • Session Duration: How long approvals last (5-1440 minutes)
  5. Click Create
  6. Copy your MCP key immediately - you won't see it again!

Step 2: Configure Your MCP Client​

  1. Open Cursor Settings (Cmd+, on Mac or Ctrl+, on Windows)
  2. Search for "MCP" or navigate to Features → Model Context Protocol
  3. Click Edit Config to open your MCP configuration file
  4. Add your Quave Cloud MCP server:
{
  "mcpServers": {
    "quave-cloud": {
      "url": "https://mcp.quave.cloud/",
      "headers": {
        "authorization": "YOUR_MCP_KEY_HERE"
      }
    }
  }
}
  1. Save the file and restart Cursor
  2. Look for the MCP indicator in Cursor - this means MCP is connected!

For detailed setup instructions, see our Cursor Setup Guide

Claude Desktop App​

  1. Open the Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json
  1. Add the same configuration as shown above for Cursor
  2. Restart Claude Desktop (fully quit and reopen)
  3. Look for the 🔌 icon in the chat input

Other MCP Clients​

Any MCP-compatible client can connect using:

  • URL: https://mcp.quave.cloud/
  • Authentication: Include your MCP key in the Authorization header

Step 3: Start Using It!​

Just chat naturally with Cursor in the composer or chat panel:

Examples:

  • "List all my Quave Cloud accounts"
  • "Show me the last 50 logs from my production app"
  • "What's the current status of my staging environment?"
  • "How many pods are running in production?"
  • "Check if there are any errors in the last hour"
  • "Show me the deployment history for staging"

Understanding MCP Keys Configuration​

Enabled Scopes​

Scopes define what operations your MCP key is allowed to perform. The Quave Cloud server validates every request against these scopes - this cannot be bypassed.

ScopeWhat It AllowsRisk LevelAlways Enable?
Read OnlyView apps, logs, metrics, and account informationSafeYes
Read SecretsView secret environment variables and sensitive dataHigh RiskRarely
Write ConfigurationsUpdate app configuration, environment variables, and settingsLow RiskIf needed
Write DeploymentsDeploy, restart, scale, and manage app environmentsMedium RiskIf needed
Write DangerousDelete resources and perform irreversible actionsHigh RiskRarely
AdminAccount-level administrative operationsCriticalRarely

Security Best Practice: Only enable the scopes you actually need. Start with just "Read Only" and add others as required.

Current Tools by Scope​

Read Only (quave:read) - View apps, logs, metrics, and account information:

  • list-accounts - Lists all accounts that the authenticated user has access to
  • get-current-account - Gets the current account set for the authenticated user
  • list-apps - Lists all apps for the authenticated user
  • list-app-envs - Lists all app environments for the authenticated user
  • get-app-env - Gets the full configuration for an app environment including resources, scaling, deployment settings, security, hosts, and pending changes (may also require additional scopes: Read Secrets)
  • get-app-env-status - Gets the current runtime status and health for an app environment
  • get-app-env-metrics - Gets real-time resource metrics (CPU, memory, container count)
  • get-app-env-history - Gets the deployment history and activity timeline
  • get-app-env-pods - Gets pod-level details for an app environment
  • get-logs - Retrieves logs from an app environment with filtering and search

Read Secrets (quave:read:secrets) - View secret environment variables and sensitive data:

No primary tools for this scope, but may be required by:

  • get-app-env - Gets the full configuration for an app environment including resources, scaling, deployment settings, security, hosts, and pending changes

Write Configurations (quave:write:config) - Update app configuration, environment variables, and settings:

  • set-current-account - Sets the current account for the authenticated user
  • update-app-env-resources - Updates resource allocation for an app environment (zClouds or custom CPU/memory/disk)

Write Deployments (quave:write:deploy) - Deploy, restart, scale, and manage app environments:

  • apply-app-env-changes - Applies pending configuration changes to an app environment (like terraform apply)

Write Dangerous (quave:write:dangerous) - Delete resources and perform irreversible actions:

Tools under development for this scope

Admin (quave:admin) - Account-level administrative operations:

Tools under development for this scope

Security Level​

The Security Level controls how your MCP client prompts you for confirmation. This is implemented by the MCP client (like Claude Desktop) and provides a better user experience, but is not enforced by the Quave Cloud server.

LevelBehaviorBest For
StrictConfirm every operation - Maximum securityCritical production accounts
BalancedRecommended - Read auto-approved, writes confirmedMost users (recommended)
PermissiveMinimal confirmations - Trust automationDevelopment environments
AutoFull automation - Only confirm destructive operationsTrusted automation workflows

Important: Even if you select a permissive security level, the server will still block any operation not allowed by your Enabled Scopes. The Security Level only affects when the MCP client shows you confirmation prompts.

Example: If you only enable the "Read Only" scope:

  • Security Level = "Permissive" → No confirmations for reads (client behavior)
  • Try to deploy → ❌ Server blocks it (scope not enabled)

Session Duration​

Session Duration controls how long the MCP client remembers your approvals. This is managed by the MCP client (like Cursor), not the Quave Cloud server.

  • Min: 5 minutes (300 seconds)
  • Max: 24 hours (86,400 seconds)
  • Default: 30 minutes (1,800 seconds)

How it works (in compatible clients like Cursor):

  1. You approve a "Deployments" operation
  2. For the next 30 minutes (or your configured duration), similar deployment operations don't require re-approval
  3. After 30 minutes, you'll be prompted again

Note: Different MCP clients may implement session management differently. This setting provides guidance but is not enforced by the server.

Name (Required)​

A friendly identifier for this key. This name helps you recognize which device or application is using the key.

Requirements:

  • 3-20 characters
  • Alphanumeric with hyphens only
  • Must be unique across your MCP keys

Examples:

  • my-laptop - Personal computer
  • cursor-ide - Cursor IDE
  • work-macbook - Work machine
  • claude-desktop - Claude Desktop app

Managing Your MCP Keys​

Viewing Your Keys​

  1. Go to User Menu → MCP
  2. See all your keys with:
    • Name and creation date
    • Enabled scopes
    • Security level and session duration
    • Last used timestamp
    • Enabled/disabled status

Editing a Key​

  1. Click the Edit button next to a key
  2. Modify:
    • Enabled scopes
    • Security level
    • Session duration
  3. Click Save

Note: To change the key name or get a new key value, you must regenerate the key (see below). You cannot retrieve the raw key value after creation.

Regenerating a Key​

If you need to change the name or have lost the key value, you can regenerate it:

  1. Click the Edit button next to a key
  2. Click Regenerate Key
  3. Optionally change the name
  4. Click Regenerate Key to confirm
  5. Copy the new key immediately - you won't see it again!

Important:

  • Regenerating invalidates the old key immediately
  • All applications using the old key will stop working
  • You must update all MCP client configurations with the new key
  • The key settings (scopes, security level, session duration) are preserved

Disabling a Key​

If you suspect a key is compromised or no longer need it:

  1. Click the Toggle button to disable
  2. The key is immediately blocked at the server level
  3. Toggle again to re-enable if needed

Deleting a Key​

Warning: This is permanent!

  1. Click the Delete button
  2. Confirm the deletion
  3. The key is permanently removed

Security Best Practices​

For MCP Keys​

  1. ✅ Use different keys for different purposes - One for local development, one for work, etc.
  2. ✅ Only enable scopes you need - Start with "Read Only" and add more as required
  3. ✅ Disable keys you're not using - Reduce attack surface
  4. ✅ Delete compromised keys immediately - Create a new one if needed
  5. ✅ Review "Last Used" regularly - Spot unauthorized usage

For Production Environments​

  1. ✅ Never enable "Dangerous Operations" unless absolutely necessary
  2. ✅ Use "Strict" security level for production access
  3. ✅ Keep session duration short (15-30 minutes)
  4. ✅ Review logs regularly - Check for unexpected operations

What if a Key is Stolen?​

  1. Immediately disable the key in the Quave Cloud UI
  2. The key is blocked at the server level - no more requests will be processed
  3. Review recent activity to see what the attacker might have done
  4. Create a new key with appropriate scopes
  5. Update your MCP client configuration

Understanding Server vs Client Enforcement​

This is critically important for security:

✅ Server-Enforced (True Security)​

These settings are validated by the Quave Cloud server on every single request. Even if someone modifies the MCP client code or configuration, these protections remain in place:

  1. Enabled Scopes - The server checks if the requested operation is allowed by your scopes
  2. MCP Key Status - Disabled keys are rejected immediately
  3. MCP Key Validity - Invalid or expired keys are rejected

Example:

User has only enabled: quave:read

MCP Client requests: deploy-app (requires quave:write:deploy)

Quave Cloud Server response: ❌ 403 Forbidden
"Insufficient scope: quave:write:deploy required"

Result: BLOCKED, even if the MCP client tried to bypass checks

⚠️ Client-Enforced (UX Enhancement)​

These settings improve the user experience by showing confirmation prompts and managing approvals, but they depend on the MCP client's implementation:

  1. Security Level - Controls when the client shows confirmation prompts
  2. Session Duration - How long the client remembers approvals

Example:

User sets Security Level: Strict

Good MCP Client: Shows confirmation for every operation
Modified/Simple MCP Client: Might not show confirmations

BUT: The server still enforces Enabled Scopes!

Key Takeaway: Configure your Enabled Scopes carefully - this is your real security boundary. Security Level and Session Duration are convenience features that make the UX better but don't provide security guarantees.

Troubleshooting​

"MCP key not found" or "Invalid MCP key"​

Problem: The server doesn't recognize your key.

Solutions:

  1. Verify you copied the entire key (including any prefix)
  2. Check that the key hasn't been deleted
  3. Ensure there are no extra spaces in your configuration

"MCP keys cannot be used directly"​

Problem: You're trying to use an MCP key directly with the Quave Cloud API.

Explanation: MCP keys can only be used through the MCP Server. They include a shared secret validation that prevents direct API usage.

Solution: Use regular CLI/API tokens for direct API access. MCP keys are specifically for MCP client usage.

"Insufficient scope" error​

Problem: Your key doesn't have the required scope for the operation.

Example Error:

Error: Insufficient scope
Required: quave:write:deploy
Your key has: quave:read

Solution:

  1. Go to User Menu → MCP
  2. Edit your key
  3. Enable the required scope
  4. Try the operation again

Client shows no confirmation even with "Strict" security​

Problem: The MCP client (Cursor, Claude Desktop, etc.) isn't showing confirmation prompts.

Explanation: Security Level is a client-side feature. Some clients may not implement it or might have bugs.

Important: Even without client confirmations, the server still enforces your Enabled Scopes. You're protected by the server-side validation.

Session seems to last forever or expire immediately​

Problem: Session Duration doesn't seem to work as configured.

Explanation: Session Duration is implemented by the MCP client. Different clients handle this differently.

Your protection: The server continuously validates your Enabled Scopes, regardless of session behavior.

Available MCP Tools​

All MCP tools are accessible through natural language conversation with Cursor or other MCP clients.

Read Only (quave:read)

list-accounts
Lists all accounts that the authenticated user has access to
Example: "Show me all my accounts"

get-current-account
Gets the current account set for the authenticated user
Example: "Which account am I using?"

list-apps
Lists all apps for the authenticated user
Example: "List all my apps"

list-app-envs
Lists all app environments for the authenticated user
Example: "Show me all environments for my web app"

get-app-env
Gets the full configuration for an app environment including resources, scaling, deployment settings, security, hosts, and pending changes
May also require additional scopes: Read Secrets
Example: "Use get-app-env"

get-app-env-status
Gets the current runtime status and health for an app environment
Example: "Is production running?"

get-app-env-metrics
Gets real-time resource metrics (CPU, memory, container count)
Example: "What's the CPU usage of staging?"

get-app-env-history
Gets the deployment history and activity timeline
Example: "Show me the last 10 deployments"

get-app-env-pods
Gets pod-level details for an app environment
Example: "How many pods are running?"

get-logs
Retrieves logs from an app environment with filtering and search
Example: "Show me error logs from production in the last hour"

Write Configurations (quave:write:config)

set-current-account
Sets the current account for the authenticated user
Example: "Switch to my work account"

update-app-env-resources
Updates resource allocation for an app environment (zClouds or custom CPU/memory/disk)
Example: "Use update-app-env-resources"

Write Deployments (quave:write:deploy)

apply-app-env-changes
Applies pending configuration changes to an app environment (like terraform apply)
Example: "Use apply-app-env-changes"

FAQ​

Q: What's the difference between MCP keys and CLI tokens? A: CLI tokens are for direct API access or CLI usage. MCP keys are specifically for MCP clients and include additional security validation.

Q: Can I use the same key on multiple devices? A: Yes, but we recommend creating separate keys for each device for better security and tracking.

Q: How do I know if my key was used? A: Check the "Last Used" timestamp on the MCP Keys page.

Q: Can I use MCP keys in CI/CD pipelines? A: MCP keys are designed for interactive use with AI assistants like Cursor. For CI/CD, use regular CLI/API tokens instead.

Q: Is my MCP key encrypted? A: Yes, MCP keys are encrypted at rest using AES-256-CBC encryption.

Q: Can I change the name of my MCP key? A: Yes, use the "Regenerate Key" feature when editing a key. This lets you change the name and generates a new key value. Note that the old key stops working immediately.

Q: What happens to my old key when I regenerate? A: The old key is invalidated immediately and stops working. You must update all MCP client configurations with the new key value. Your key settings (scopes, security level, session duration) remain the same.

Q: If I select "Permissive" security level, can someone destroy my production? A: No! Even with "Permissive" security level, the server enforces your Enabled Scopes. If you don't enable "Dangerous Operations", deletion operations will be blocked by the server.

Q: Can someone modify their MCP client to bypass security? A: They can bypass client-side features (confirmations, session management), but they CANNOT bypass server-enforced Enabled Scopes. Your scope configuration is your true security boundary.

Resources​

Support​

Need help with MCP? Contact our support team