Skip to content

MCP

Connect your AI client to Wodby to inspect applications, plan migrations, deploy, and troubleshoot. This guide applies to Wodby 2.

Before you connect

  • Sign in to Wodby and choose the organization you want the client to access.
  • Use an MCP-capable client. Prefer OAuth and start with mcp:read.
  • Give your client repository access separately when needed. MCP does not grant access to your existing host, database, or DNS provider.

Your client acts within your Wodby permissions. Connecting does not authorize changes. Review costs and data impact before approving operations. Logs may contain private application data; never paste credentials into a conversation. Ordinary API keys do not have OAuth scope restrictions, but container command tools require OAuth with mcp:exec.

Connect your client

For setup instructions in the dashboard, open your organization's Agents > Connect an agent page. After authorization, use Agents to review access and activity.

Use this remote HTTP endpoint:

https://mcp.wodby.com/mcp

Open the instructions for your client. Merge configuration with existing entries rather than replacing them. Client versions and organization policies can affect available features.

Codex

Codex can add Wodby from the CLI:

codex mcp add wodby --url https://mcp.wodby.com/mcp

If Codex does not open the authorization flow during add, run:

codex mcp login wodby

For an authorized task that needs operational permissions, explicitly request them:

codex mcp login wodby --scopes mcp:read,mcp:operate

Review the new browser consent before approving. Other operations may require different scopes.

Codex stores MCP servers in ~/.codex/config.toml, or in .codex/config.toml for a trusted project. The equivalent manual configuration is:

[mcp_servers.wodby]
url = "https://mcp.wodby.com/mcp"

In the Codex terminal UI, use /mcp to check connected MCP servers.

See the official Codex MCP guide for client configuration options.

For manual-key configuration, see API-key fallback below.

Claude Code

Claude Code can connect to remote HTTP MCP servers directly:

claude mcp add --transport http wodby https://mcp.wodby.com/mcp

Then run the OAuth login flow (in versions that support CLI login):

claude mcp login wodby

Alternatively, start Claude Code and use /mcp to authorize Wodby. Check the server with claude mcp get wodby. See the Claude Code MCP reference.

Claude Desktop

Install Node.js and npm, and make sure Claude Desktop can find npx.

Open the Claude Desktop MCP configuration file and add the Wodby server:

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

code "$env:APPDATA\Claude\claude_desktop_config.json"

{
  "mcpServers": {
    "wodby": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.wodby.com/mcp"
      ]
    }
  }
}

Save the file, restart Claude Desktop, and approve the Wodby browser authorization when prompted.

OpenCode

Add this entry to your opencode.json, merging it with any existing configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "wodby": {
      "type": "remote",
      "url": "https://mcp.wodby.com/mcp",
      "enabled": true
    }
  }
}

Then authorize and inspect the connection:

opencode mcp auth wodby
opencode mcp list

Review the organization and scopes in browser consent. See OpenCode MCP servers.

Hermes

Merge this into ~/.hermes/config.yaml:

mcp_servers:
  wodby:
    url: "https://mcp.wodby.com/mcp"
    auth: oauth

Run authorization from a fresh terminal, then restart the session or use /reload-mcp:

hermes mcp login wodby

A remote gateway needs a supported callback or interactive authorization handoff. Do not assume that a device-code flow is available on Wodby. See Hermes MCP configuration.

Generic clients

Install Node.js and npm first, and make sure your client can find npx.

For MCP clients that run local server commands, use mcp-remote without custom headers. It discovers Wodby's OAuth metadata, opens the browser flow, and stores the returned MCP token locally:

{
  "mcpServers": {
    "wodby": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.wodby.com/mcp"
      ]
    }
  }
}

Restart your MCP client after changing its configuration.

API-key fallback

For clients or scripts that cannot complete OAuth, use a dedicated API key and X-API-KEY. Ordinary API keys do not gain the restrictions of an OAuth scope grant:

{
  "mcpServers": {
    "wodby": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.wodby.com/mcp",
        "--header",
        "X-API-KEY: ${WODBY_API_KEY}"
      ]
    }
  }
}

Provide WODBY_API_KEY through the environment of the client process or its supported secret store. Desktop apps started from a launcher may not inherit variables exported in a terminal. Do not replace the placeholder with a literal key in a shared configuration file.

Codex:

To use a manual API key instead of OAuth, configure env_http_headers:

[mcp_servers.wodby]
url = "https://mcp.wodby.com/mcp"
env_http_headers = { "X-API-KEY" = "WODBY_API_KEY" }

Set the key before starting Codex:

export WODBY_API_KEY=...
codex

Other hosts and models

The host connects to MCP and enforces its own tool-approval policy. Choosing a model through OpenRouter does not configure a Wodby connection; configure the MCP-capable host that uses that model.

For a client that only accepts marketplace plugins, confirm an appropriate Wodby plugin is available and permitted by your administrator. The downloadable Wodby skill archive is not proof of a marketplace listing. If the host cannot accept the endpoint or a suitable plugin, use a client with documented remote MCP support rather than guessing setup commands.

Verify the connection

Approve the intended organization in browser consent, then ask:

Use Wodby to identify my user and list the organizations and projects I can access.
Do not change anything. Ask which project to use if the target is ambiguous.

Confirm the returned identity and target. A configured server or visible tool list does not prove access to an app. If the account is wrong or access fails, stop and use connection troubleshooting.

For an existing application, replace these example names:

Show the status of app example in organization acme, including staging and its latest deployment.
Report missing evidence. Do not change the application.

Choose a task

Ask the agent to load wodby2-get-started with get_wodby_guidance, or choose a walkthrough:

Skills provide the workflow; tools perform individual steps. Installing skills locally is optional. Read Permissions and audit history before granting more access. A plan does not approve deployment, and staging approval does not approve production cutover.

Technical reference

For custom clients and exact behavior, see the protocol, authentication, task, and log reference and tool catalog. Use the connected server's schemas for current inputs and capabilities.

Development workspaces

Use workspace MCP controls to inspect a development workspace, retrieve the owner's SSH connection details, rerun preparation, or pause and resume it. Connect your editor or agent over SSH separately to work on the checkout.