Exposed MCP Tools
Relevant source files
The following files were used as context for generating this wiki page:The Dokku MCP server exposes Dokku's management capabilities through a set of "tools" that are compliant with the Model Context Protocol (MCP). These tools allow clients, such as Large Language Models (LLMs) or IDE extensions, to perform actions on a Dokku instance in a structured and predictable way. The system is designed with a plugin-based architecture, where different modules contribute their own sets of tools, resources, and prompts.
Each tool is defined by a name, a description, a schema for its parameters, and a handler function that executes the logic. This modular approach allows for easy extension of the server's capabilities. The primary interfaces for providing these capabilities are ToolProvider, ResourceProvider, and PromptProvider.
Sources: README.md, internal/server-plugin/domain/server-plugin.go:10-20
Tool Response Structure
All tool calls return a standardized JSON envelope, ensuring that clients receive a consistent response format regardless of the tool being called. The ToolResponse struct defines this envelope, which includes status, messages, and optional data payloads.
Sources: internal/server/mcp_envelope.go:21-31
The diagram below illustrates the structure of the ToolResponse object.
The fields of the ToolResponse are described in the table below:
| Field | Type | Description |
|---|---|---|
Status | ToolStatus (string) | The high-level status of the call: ok, error, or partial. |
Code | string | An optional machine-readable code for the status (e.g., APP_NOT_FOUND). |
Message | string | A human-readable message describing the result of the operation. |
RequestID | string | An optional ID to correlate the request and response. |
Data | map[string]json.RawMessage | A map containing any data returned by the tool, with values as raw JSON messages. |
Links | []ToolLink | An optional array of suggested follow-up actions for the client. |
Hint | string | An optional hint for the user or LLM on how to proceed, especially in case of an error. |
Sources: internal/server/mcp_envelope.go:21-31, internal/server-plugins/domain/plugin.go:101-108
Tool Discovery
Clients can discover available tools and their usage through the resources provided by the onboarding plugin. This plugin does not expose action-oriented tools itself but provides meta-resources that index the capabilities of all other active plugins.
The primary discovery resources are:
dokku://onboarding/capabilities: A JSON index of all available tools, resources, and prompts.dokku://onboarding/intent-map: A JSON object that maps common user intents (e.g., "deploy", "scale") to the corresponding MCP tool and its required parameters.
Sources: internal/server-plugins/onboarding/plugin.go:37-54
The following flowchart shows how a client can use these resources to discover and execute a tool.
Core Plugin Tools
The core plugin provides fundamental tools for server introspection.
Sources: internal/server-plugins/core/plugin.go
| Tool Name | Description | Parameters |
|---|---|---|
get_server_logs | Get recent dokku-mcp server logs from an in-memory buffer. | last (number): Number of lines to return.level (string): Filter by level.contains (string): Filter by substring. |
This tool is only exposed if expose_server_logs is enabled in the server configuration.
Sources: internal/server-plugins/core/plugin.go:106-114, internal/server-plugins/core/plugin.go:120-133
Application Plugin Tools
The apps plugin is the most extensive, providing a comprehensive suite of tools for managing Dokku applications. It handles creation, deployment, scaling, and configuration.
Sources: internal/server-plugins/app/plugin.go
Summary of App Tools
| Tool Name | Description |
|---|---|
create_app | Create a new Dokku application. |
deploy_app | Deploy an application from a Git repository. |
scale_app | Scale application processes up or down. |
configure_app | Set environment variables for an application. |
get_app_status | Get comprehensive status for an application. |
Sources: internal/server-plugins/app/plugin.go:66-96
Tool Parameters
create_app
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Application name (lowercase, alphanumeric, hyphens allowed). |
buildpack | string | No | Specific buildpack to use. |
no_vhost | boolean | No | Disable default vhost creation. |
Sources: internal/server-plugins/app/plugin.go:127-139
deploy_app
| Parameter | Type | Required | Description |
|---|---|---|---|
app_name | string | Yes | Name of the application to deploy. |
repo_url | string | Yes | URL of the Git repository. |
git_ref | string | No | Git reference (branch, tag, or commit). Defaults to main. |
force | boolean | No | Force deployment even if no changes are detected. |
Sources: internal/server-plugins/app/plugin.go:141-158
scale_app
| Parameter | Type | Required | Description |
|---|---|---|---|
app_name | string | Yes | Name of the application to scale. |
process_type | string | No | Process type to scale (e.g., web, worker). |
instances | number | Yes | Number of instances to scale to. |
Sources: internal/server-plugins/app/plugin.go:160-174
configure_app
| Parameter | Type | Required | Description |
|---|---|---|---|
app_name | string | Yes | Name of the application to configure. |
config | object | Yes | Key-value pairs of environment variables. |
Sources: internal/server-plugins/app/plugin.go:176-191
get_app_status
| Parameter | Type | Required | Description |
|---|---|---|---|
app_name | string | Yes | Name of the application to get status for. |
Sources: internal/server-plugins/app/plugin.go:193-200
Example Workflow: Create and Deploy
The following sequence diagram illustrates a common workflow where a client creates a new application and then deploys it.
Domain Plugin Tools
The domain plugin manages global and application-specific domains within Dokku.
Sources: internal/server-plugins/domain/plugin.go
| Tool Name | Description | Parameters |
|---|---|---|
list_global_domains | List all global domains. | None |
add_global_domain | Add a new global domain. | domain_name (string, required): The domain to add. |