Understanding MCP Concepts

Relevant source files

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

• internal/server/mcp_envelope.go
• README.md
• internal/server-plugin/domain/server-plugin.go
• internal/server-plugins/app/plugin.go
• internal/server-plugins/onboarding/plugin.go
• cmd/gen-mcp-json/main.go
• internal/dokku-api/client_blacklist_test.go

The Dokku MCP Server uses the Model Context Protocol (MCP) to expose Dokku's management capabilities to Large Language Models (LLMs). This allows AI agents and MCP-compatible clients (like Cursor, Claude, etc.) to interact with and manage a Dokku instance programmatically. The core idea is to provide a structured, discoverable, and safe interface for an AI to operate a PaaS.

This system is built on a plugin-based architecture where different Dokku features are encapsulated as distinct capabilities. These capabilities are exposed to the LLM through three main primitives: Resources, Tools, and Prompts. This document explains these fundamental concepts and how they work together within the dokku-mcp project.

Sources: README.md:5-8, README.md:313-317

Connecting an MCP Client

An MCP-compatible client connects to the dokku-mcp server by running it as a subprocess. The configuration for this connection is defined in a JSON file, typically named .mcp.json. This file tells the client how to start the server and what environment variables to provide.

Sources: README.md:41-43

The .mcp.json Configuration

The server provides a make gen-mcp-json command which can generate this configuration file based on the project's settings. The structure is as follows:

{
  "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"
      }
    }
  }
}

Sources: README.md:45-59, cmd/gen-mcp-json/main.go:17-22, cmd/gen-mcp-json/main.go:53-62

The key fields are:

Field	Description	Source
command	The absolute path to the dokku-mcp executable binary.	[README.md:60](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/README.md#L60), [cmd/gen-mcp-json/main.go:42-51](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/cmd/gen-mcp-json/main.go#L42-L51)
args	An array of command-line arguments to pass to the server (usually empty).	[cmd/gen-mcp-json/main.go:59](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/cmd/gen-mcp-json/main.go#L59)
env	A key-value map of environment variables for configuring the server's behavior, such as SSH connection details and security settings.	[README.md:50-57](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/README.md#L50-L57), [cmd/gen-mcp-json/main.go:34-38](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/cmd/gen-mcp-json/main.go#L34-L38)

Connection Flow

The following diagram illustrates how an MCP client uses the .mcp.json file to start and communicate with the server.

Sources: README.md:41-61, README.md:144-149

The Plugin-Based Architecture

The server's functionality is organized into a modular, plugin-based architecture. Each plugin encapsulates a specific set of Dokku features (e.g., app, core, domain). This design allows for clear separation of concerns and makes the system extensible.

Sources: README.md:313-317, internal/server-plugins/app/plugin.go

Core Plugin Interfaces

The plugin system is defined by a set of Go interfaces. A single plugin can implement one or more of these interfaces to expose different types of capabilities.

Interface	Purpose
ServerPlugin	The base interface providing metadata like ID, name, and description.
ResourceProvider	Implemented by plugins that provide read-only data sources (Resources).
ToolProvider	Implemented by plugins that provide executable functions (Tools).
PromptProvider	Implemented by plugins that provide pre-defined templates for LLM guidance (Prompts).

Sources: internal/server-plugin/domain/server-plugin.go:8-30

The relationship between these interfaces is shown below.

Sources: internal/server-plugin/domain/server-plugin.go:8-30, internal/server-plugins/app/plugin.go:27-108

MCP Primitives: Resources, Tools, and Prompts

The MCP standardizes interactions through three primary concepts: Resources, Tools, and Prompts.

Resources: Discoverable Information

Resources are read-only information sources identified by a unique URI. They allow an LLM to query the state of the Dokku instance.

• Structure: A Resource is defined by its URI, Name, Description, MIMEType, and a Handler function that fetches the data.
• Examples:
  • dokku://apps/list: Returns a JSON list of all applications.
  • dokku://onboarding/quickstart: Provides a Markdown guide for the LLM.
  • dokku://core/server/info: Returns a comprehensive JSON object with server status.

Sources: internal/server-plugin/domain/server-plugin.go:32-38, internal/server-plugins/app/plugin.go:73-82, internal/server-plugins/core/plugin.go:78-96, internal/server-plugins/onboarding/plugin.go:40-58

Tools: Actionable Capabilities

Tools are functions that the LLM can execute to perform actions and modify the state of the Dokku instance. They are the primary mechanism for management.

• Structure: A Tool is defined by its Name, Description, a Builder function that defines its parameters for the LLM, and a Handler function that contains the execution logic.
• Security: The server includes a blacklist to prevent the execution of dangerous commands (e.g., destroy, uninstall). The command validator also blocks shell metacharacters like ;, |, and $.
• Examples:
  • create_app: Creates a new Dokku application.
  • deploy_app: Deploys an application from a Git repository.
  • scale_app: Scales the number of running processes for an app.

Sources: internal/server-plugin/domain/server-plugin.go:40-45, internal/server-plugins/app/plugin.go:85-108, README.md:51, internal/dokku-api/client_blacklist_test.go:28-44, internal/dokku-api/client_blacklist_test.go:76-105

The following diagram shows the sequence of a tool call:

Sources: internal/server-plugins/app/plugin.go:221-236, internal/server-plugins/domain/infrastructure/dokku_adapter.go:23-26

Prompts: Guided Interactions

Prompts are pre-defined templates that guide an LLM to perform complex or diagnostic tasks. They help the LLM construct a useful query by providing a structured starting point.

• Structure: A Prompt is defined by its Name, Description, a Builder that specifies its arguments, and a Handler that generates the prompt text.
• Example: The app_doctor prompt takes an app_name and generates a detailed request for diagnosing application health.

Sources: internal/server-plugin/domain/server-plugin.go:47-52, internal/server-plugins/app/plugin.go:102-114, internal/server-plugins/app/plugin.go:343-366

The MCP Response Envelope

To ensure the LLM can reliably understand the outcome of a tool call, all tool handlers return a standardized JSON object called ToolResponse. This envelope provides a consistent structure for success, error, and partial success scenarios.

Sources: internal/server/mcp_envelope.go:19-30

The ToolResponse struct is defined as:

// ToolResponse is the canonical envelope returned by tools
type ToolResponse struct {
	Status    ToolStatus       `json:"status"`
	Code      string           `json:"code,omitempty"`
	Message   string           `json:"message,omitempty"`
	RequestID string           `json:"requestId,omitempty"`
	Data      ToolResponseData `json:"data,omitempty"`
	Links     []ToolLink       `json:"links,omitempty"`
	Hint      string           `json:"hint,omitempty"`
}

Sources: internal/server/mcp_envelope.go:19-30

Field	Type	Description
Status	string	The high-level status: ok, error, or partial.
Code	string	A machine-readable code for the status (e.g., APP_NOT_FOUND).
Message	string	A human-readable message describing the outcome.
Data	object	A JSON object containing any data returned by the tool.
Links	array	Suggested follow-up actions for the LLM.
Hint	string	A hint for the LLM on how to proceed, especially on error.

Sources: internal/server/mcp_envelope.go:11-30, internal/server-plugins/domain/plugin.go:102-108

An example error response from the domain plugin:

{
  "status": "error",
  "code": "DOMAINS_LIST_FAILED",
  "message": "Failed to list global domains: ..."
}

Sources: internal/server-plugins/domain/plugin.go:102-108

Transport Modes

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

1. stdio (default): Communication occurs over standard input/output, suitable for direct process communication with local clients.
2. sse (Server-Sent Events): An HTTP-based transport for web-based or remote clients.

Sources: README.md:144-149