MCP Server (Model Context Protocol)

Hydra Deploy includes a built-in MCP server that lets AI coding agents interact with your deployment platform. It can list projects, checking deployment status, deploying versions, and more.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and data sources. Hydra Deploy implements an MCP server that exposes your deployment operations as tools that AI agents can use.

Supported AI Clients

Any MCP-compatible client can connect to Hydra Deploy, including:

• Claude Code (Anthropic’s CLI)
• Cursor (AI code editor)
• Windsurf (Codeium’s editor)
• Claude Desktop
• Any other client that supports the MCP Streamable HTTP transport

MCP API Keys

MCP uses its own API keys, separate from the organisation API keys used by the External API. The key difference is that MCP keys are linked to your user account: any deployments triggered through MCP are attributed to you personally, providing a clear audit trail.

Creating an MCP Key

1. Go to Settings > MCP Keys
2. Click Create New MCP Key
3. Enter a descriptive name (e.g., “Claude Code Laptop”)
4. Click Create Key
5. Copy the generated key. You’ll need it for your MCP client configuration

Managing MCP Keys

The MCP Keys page shows all keys in your organisation:

• Name: the descriptive name you gave the key
• Key: the API key value (click to copy)
• Created By: the user who created the key
• Used Times: how many times the key has been used
• Last Used At: when the key was last used
• Created At: when the key was created
• Delete: remove a key that’s no longer needed

Who Can Create MCP Keys

Users with the ORG_OWNER, ORG_MANAGER, or ORG_USER role can create MCP keys. Each key is tied to the user who created it.

Connecting Your AI Client

Add Hydra Deploy to your MCP client configuration:

{
  "mcpServers": {
    "hydra": {
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "x-api-key": "<your-mcp-key>"
      }
    }
  }
}

Claude Code

Add to your Claude Code MCP configuration (.claude/mcp.json or via the settings UI):

{
  "mcpServers": {
    "hydra": {
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "x-api-key": "<your-mcp-key>"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (Settings > MCP):

{
  "mcpServers": {
    "hydra": {
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "x-api-key": "<your-mcp-key>"
      }
    }
  }
}

Authentication

The MCP server accepts your API key via two methods:

• x-api-key header: x-api-key: <your-key> (recommended for MCP clients)
• Authorization header: Authorization: Bearer <your-key>

Available Tools

Once connected, your AI agent has access to these tools:

list_projects

List all projects in your organisation.

Returns: Array of projects with id, name, and code.

list_applications

List all applications in your organisation.

Returns: Array of applications with id, name, and code.

list_environments

List all environments in your organisation.

Returns: Array of environments with id and name.

list_versions

List available versions for a specific application.

Parameters:

• appCode (string, required): Application code (e.g., “hydra-backend”)

Returns: Array of versions with id and version.

get_project

Get full project details including connected applications and environments.

Parameters:

• projectCode (string, required): Project code

Returns: Complete project object with all connections.

get_project_matrix

Get the deployment matrix for a project. Shows which version of each application is deployed in each environment for a project.

Parameters:

• projectCode (string, required): Project code

Returns: Project name and deployment matrix data.

deploy

Deploy a specific version to an application + project + environment combination. The deployment is attributed to the MCP key owner.

Parameters:

• version (string, required): Version string to deploy (e.g., “1.2.0”)
• appCode (string, required): Application code (e.g., “hydra-backend”)
• projectCode (string, required): Project code
• envId (string, required): Environment ID to deploy to

Returns: The created deployment object.

get_current_deployments

Get the currently deployed versions for an application within a project, across all environments.

Parameters:

• appCode (string, required): Application code
• projectCode (string, required): Project code

Returns: Current deployment state per environment.

get_deployment

Get details and status of a specific deployment.

Parameters:

• deploymentId (string, required): Deployment ID

Returns: Full deployment details including status, logs, and metadata.

list_deployments

List the 20 most recent deployments for the organisation.

Returns: Array of deployments with id, status, version, application, project, environment, triggeredBy, and createdAt.

redeploy

Re-trigger an existing deployment by its ID.

Parameters:

• deploymentId (string, required): Deployment ID to redeploy

Returns: The new deployment object.

cancel_deployment

Cancel an in-progress deployment.

Parameters:

• deploymentId (string, required): Deployment ID to cancel

Returns: Cancellation result.

Sessions

The MCP server uses Streamable HTTP transport with session management:

• Each MCP connection creates a session identified by a unique session ID
• Sessions are maintained via the mcp-session-id header
• Idle sessions expire after 30 minutes of inactivity
• Sessions can be explicitly closed with a DELETE request to the MCP endpoint

Example Workflows

Deploy via AI Agent

Ask your AI agent:

“Deploy version v1.2.3 of the backend to the staging environment in the main project”

The agent will:

1. Call list_applications to find the app code
2. Call list_versions to verify the version exists
3. Call get_project to find the project and environment details
4. Call deploy with the correct parameters
5. Optionally call get_deployment to check the deployment status

Check Deployment Status

“What versions are currently deployed in the production project?”

The agent will:

1. Call get_project_matrix with the project code
2. Present the deployment matrix showing versions per app per environment

Redeploy After a Fix

“The last deployment to staging failed. Redeploy it.”

The agent will:

1. Call list_deployments to find the failed deployment
2. Call redeploy with the deployment ID
3. Call get_deployment to monitor the new deployment status

Security

• MCP keys are scoped to your organisation, so they can only access your organisation’s resources
• Each key is linked to a specific user, and all actions are attributed to that user in the audit trail
• Keys track usage count and last-used timestamp for monitoring
• Delete unused keys regularly to maintain security
• MCP keys are separate from the External API keys, providing independent access control