Connecting an MCP Client

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• internal/dokku-api/client.go
• internal/dokku-api/ssh_integration.go
• internal/server-plugins/onboarding/plugin.go
• scripts/setup-dokku-local.sh
• internal/dokku-api/client_blacklist_test.go
• internal/dokku-api/ssh_auth_test.go

The dokku-mcp server acts as a bridge, exposing Dokku's management capabilities to any client that supports the Model Context Protocol (MCP). This allows tools like IDEs (Cursor, Zed), agentic frameworks, and other LLM-powered clients to interact with and manage a Dokku instance.

Connecting a client involves two main steps: configuring the dokku-mcp server to connect to your Dokku host, and then configuring the MCP client to launch and communicate with the dokku-mcp server. The server primarily uses SSH to execute commands on the remote Dokku host.

Sources: README.md:7-11

Connection Architecture

The following diagram illustrates the relationship between the MCP client, the dokku-mcp server, and the Dokku host.

This diagram shows that the MCP Client starts the dokku-mcp server process. The server then establishes an SSH connection to the Dokku host to execute commands.

Sources: README.md:21-38, internal/dokku-api/client.go:100-112

Client Configuration (mcp.json)

MCP-compatible clients discover servers through a JSON configuration file, typically named .mcp.json or a variant like .cursor/mcp.json. This file tells the client how to start the dokku-mcp server.

Sources: README.md:21-23

Example Configuration

{
  "mcpServers": {
    "dokku": {
      "command": "/home/user/dokku-mcp/build/dokku-mcp",
      "args": [],
      "env": {
        "DOKKU_MCP_SECURITY_BLACKLIST": "destroy,uninstall,remove",
        "DOKKU_MCP_SSH_HOST": "127.0.0.1",
        "DOKKU_MCP_SSH_KEY_PATH": "/home/user/.ssh/id_rsa",
        "DOKKU_MCP_SSH_PORT": "22",
        "DOKKU_MCP_SSH_USER": "dokku"
      }
    }
  }
}

Remember to replace the command path with the absolute path to your dokku-mcp binary.

Sources: README.md:25-38

Environment Variables

The server is configured via environment variables passed in the env block of the mcp.json file.

Variable	Description	Example
DOKKU_MCP_SSH_HOST	The hostname or IP address of the Dokku server.	127.0.0.1
DOKKU_MCP_SSH_PORT	The SSH port for the Dokku server.	22
DOKKU_MCP_SSH_USER	The SSH user for the Dokku server, typically dokku.	dokku
DOKKU_MCP_SSH_KEY_PATH	The absolute path to the SSH private key for authentication. If omitted, it may try to use an ssh-agent.	/home/user/.ssh/id_rsa
DOKKU_MCP_SECURITY_BLACKLIST	A comma-separated list of dangerous command substrings to block.	destroy,uninstall,remove
DOKKU_MCP_LOG_LEVEL	Sets the logging level for the server.	debug
DOKKU_MCP_TRANSPORT_TYPE	Sets the transport mode. Can be stdio (default) or sse.	sse

Sources: README.md:31-36, README.md:143-146, scripts/setup-dokku-local.sh:98-101

Server Configuration Methods

While environment variables in mcp.json are the primary method for client-side setup, the server can also be configured using a config.yaml file. Environment variables always override settings from a configuration file.

Sources: README.md:99-101

config.yaml

The server looks for config.yaml in the following locations:

1. ./config.yaml (local directory)
2. ~/.dokku-mcp/config.yaml (user-specific)
3. /etc/dokku-mcp/config.yaml (system-wide)

Sources: README.md:104-108

A minimal config.yaml for a local development setup looks like this:

# Dokku MCP Server Configuration for Local Development
ssh:
  host: "127.0.0.1"
  port: 3022
  user: "dokku"
  key_path: ".ssh/dokku_mcp_test"

log_level: "debug"

security:
  blacklist:
    - "destroy"
    - "uninstall"
    - "remove"

Sources: scripts/setup-dokku-local.sh:86-107

SSH Connection and Authentication

The dokku-mcp server relies on an SSHConnectionManager to handle all interactions with the Dokku host. This manager uses an SSHAuthService to determine the best authentication method.

Sources: internal/dokku-api/ssh_integration.go:13-21

This diagram shows the main components responsible for managing the SSH connection.

Sources: internal/dokku-api/ssh_integration.go

Authentication Logic

The SSHAuthService determines the authentication method with the following priority:

1. SSH Agent: If an ssh-agent is running, it will be used.
2. Configured Key: If DOKKU_MCP_SSH_KEY_PATH is set (or ssh.key_path in config.yaml), that specific key will be used.
3. Default Key: If no key is configured, it falls back to checking for ~/.ssh/id_rsa.
4. SSH Agent (Fallback): If none of the above are found, it attempts to use ssh-agent as a last resort.

Sources: internal/dokku-api/ssh_auth_test.go:111-120

Security

Command Blacklist

To prevent accidental or malicious use of destructive commands, the server implements a command blacklist. This is configured via the DOKKU_MCP_SECURITY_BLACKLIST environment variable or the security.blacklist array in config.yaml.

The validation logic is as follows:

This flow shows that every command is checked against the blacklist and for dangerous characters before execution.

Sources: internal/dokku-api/client.go:16-23, internal/dokku-api/client_blacklist_test.go:27-33

The validation logic checks if the command name contains any of the blacklisted patterns.

// internal/dokku-api/client.go:19-23
for _, blacklistedPattern := range c.blacklistedCommands {
    if strings.Contains(commandName, blacklistedPattern) {
        return fmt.Errorf("command is blacklisted (matches pattern '%s'): %s", blacklistedPattern, commandName)
    }
}

Sources: internal/dokku-api/client.go:19-23

Dangerous Character Validation

In addition to the blacklist, the server also validates that command names and arguments do not contain characters that could be used for command injection, such as ;, &, |, and $.

Sources: internal/dokku-api/client.go:27-39

Transport Modes

The server supports two transport modes for communication with the MCP client. This is configured with the DOKKU_MCP_TRANSPORT_TYPE environment variable.

Mode	Description	Default
stdio	Standard input/output. Used for direct process communication with local clients like IDE extensions.	Yes
sse	Server-Sent Events. An HTTP-based transport for web clients.	No

For sse transport, CORS can be configured. See the docs/CORS.md file for more details.

Sources: README.md:143-159

Client Onboarding and Discovery

Once a client is connected, it can discover the server's capabilities by reading special resources. These resources provide a machine-readable index of available tools, prompts, and other resources.

• dokku://onboarding/quickstart: A human-readable Markdown guide to getting started.
• dokku://onboarding/capabilities: A JSON index of all available tools, resources, and prompts.
• dokku://onboarding/intent-map: A JSON file mapping common user intents (e.g., "deploy", "scale") to specific dokku-mcp tools.

An MCP client can use these resources to understand how to interact with the Dokku server.

Sources: internal/server-plugins/onboarding/plugin.go:30-51

Summary

Connecting an MCP client to dokku-mcp is a straightforward process. The key is to provide the server with the correct SSH credentials for the Dokku host and to configure the client to launch the dokku-mcp binary with these credentials in its environment. The mcp.json file is the standard mechanism for this client-side configuration. Security features like the command blacklist should be configured to prevent unintended operations.