#Zephyr API MCP

The Zephyr API MCP server connects compatible AI assistants to the Zephyr Cloud control plane. You can use natural-language requests to inspect organizations and applications, review deployment state, and perform authorized operations such as promoting a version or updating a tag.

Production endpoint:

https://mcp.zephyr-cloud.io/mcp

#Prerequisites

You need:

• A Zephyr Cloud account
• Access to the organizations and applications you want to manage
• An MCP client that supports remote HTTP servers and OAuth

The server opens the standard Zephyr sign-in flow. You do not need to create or paste an API token.

#Connect an MCP client

#Claude Code

Add the remote server for your user account:

claude mcp add --transport http --scope user zephyr https://mcp.zephyr-cloud.io/mcp

Start Claude Code, open /mcp, select zephyr, and complete the Zephyr login flow.

#Codex

Add the server, then sign in:

codex mcp add zephyr --url https://mcp.zephyr-cloud.io/mcp
codex mcp login zephyr

Your browser opens the Zephyr login page. After authorization, restart or refresh the MCP connection if your current Codex session does not show the server.

#Cursor

Create .cursor/mcp.json in your project, or add the same server to your global Cursor MCP configuration:

{
  "mcpServers": {
    "zephyr": {
      "url": "https://mcp.zephyr-cloud.io/mcp"
    }
  }
}

Open Cursor Settings → Tools & MCP, enable zephyr, and complete the Zephyr login flow. See Cursor's MCP documentation for global configuration and server controls.

#Gemini CLI

Add Zephyr to your user configuration:

gemini mcp add --transport http --scope user zephyr https://mcp.zephyr-cloud.io/mcp

Start Gemini CLI, run /mcp auth zephyr, and complete the Zephyr login flow. See the Gemini CLI MCP documentation for configuration and authentication details.

#VS Code with GitHub Copilot

Add Zephyr to your VS Code user profile:

code --add-mcp '{"name":"zephyr","type":"http","url":"https://mcp.zephyr-cloud.io/mcp"}'

Alternatively, run MCP: Add Server from the Command Palette, choose HTTP, and enter the production endpoint. Start the server and complete the Zephyr login flow when prompted. See Use MCP servers in VS Code for workspace and user configuration options.

#Other MCP clients

Use the production endpoint in your client's remote MCP configuration. For clients that accept JSON configuration, the shape is typically:

{
  "mcpServers": {
    "zephyr": {
      "url": "https://mcp.zephyr-cloud.io/mcp"
    }
  }
}

Configuration fields differ between clients. Choose the HTTP or Streamable HTTP transport when the client asks for a transport type.

#How the MCP server works

The server uses Code Mode to expose the full Zephyr API through two tools:

API paths are not hard-coded into the MCP server. It loads the current OpenAPI description from the production Zephyr API and uses that description to discover available operations.

The normal sequence is:

1. The assistant uses search to identify the correct API operations.
2. It uses execute to read or change data through those operations.
3. For changes, it reads the affected resource again to verify the final state.

You normally do not need to mention these tools. Describe the outcome you want and provide the relevant Zephyr identifiers.

#Explore your Zephyr account

Start with read-only requests when you do not know the exact organization, project, or application name:

List the Zephyr organizations I can access.

In organization "acme", list its projects and the applications in each project.

Show the latest ten versions, tags, and environments for
header-component.ecommerce.acme.

Zephyr applications follow the {application}.{project}.{organization} identifier format. See Organization Structure for details.

#Inspect a deployment

Ask for the current state and the evidence you need:

For header-component.ecommerce.acme, show which version the "production"
tag currently resolves to and include the version's branch, commit, and URL.

Compare versions 124 and 125 of header-component.ecommerce.acme.
Summarize their deployment metadata and remote dependencies.

#Promote or roll back a version

For a change, provide the complete source and destination. Ask the assistant to inspect both before changing anything and to verify the result afterward:

For header-component.ecommerce.acme:
1. Inspect version 125 and the current "production" tag.
2. Deploy version 125 to the "production" tag.
3. Read the tag again and confirm which version it resolves to.

For a rollback:

For header-component.ecommerce.acme, inspect versions 124 and 125 and the
current "production" tag. If version 124 is available, move "production" back
to version 124, then read the tag again and report the final state.

Review Versions, Tags & Environments, and Instant Rollbacks before changing production routing.

#Troubleshooting

#Authentication fails

Reconnect the MCP server and repeat the Zephyr login flow. A 401 response means the client did not provide a valid MCP credential.

For Codex:

codex mcp login zephyr

#The server appears unavailable

Check the public health endpoint:

curl -fsS https://mcp.zephyr-cloud.io/healthz

A healthy server returns:

{ "ok": true }