DuploCloud MCP Server

A Model Context Protocol (MCP) server for DuploCloud. Dynamically discovers duploctl commands and exposes them as MCP tools so AI agents and compatible clients can query infrastructure state and perform auditable actions.

Built on FastMCP and the duplocloud-client Python package. Installs as a duploctl plugin — no separate command needed.

Features

duploctl plugin -- registers as a duploctl resource via entry points; run with duploctl mcp
Automatic tool discovery -- all duploctl @Command methods are registered as MCP tools at startup
Resource and command filtering -- regex-based filters to control which tools are exposed
Pydantic model integration -- commands with models get typed input schemas instead of raw dicts
Config display -- built-in config tool and GET /config route showing live server state
Custom tool/route framework -- @custom_tool and @custom_route decorators with context injection
Dual transport -- stdio (default) or HTTP for persistent servers

Prerequisites

Python 3.10+
DuploCloud credentials (DUPLO_HOST, DUPLO_TOKEN)
A DuploCloud tenant (DUPLO_TENANT)

Installation

pip install duplocloud-mcp

For pinned version installs and alternative methods (GitHub release artifact, git tag), see the release notes.

For development:

git clone https://github.com/duplocloud/mcp.git
cd mcp
pip install -e ".[test]"

Quick Start

Set your DuploCloud credentials and start the server:

export DUPLO_HOST="https://your-portal.duplocloud.net"
export DUPLO_TOKEN="your-token"
export DUPLO_TENANT="your-tenant"

duploctl mcp

By default the server starts in stdio transport with compact mode (5 tools). To use HTTP:

duploctl mcp --transport http

Verify it's running:

curl http://localhost:8000/health
# {"status":"healthy","service":"duplocloud-mcp"}

curl http://localhost:8000/config
# Full server configuration including registered tools

Configuration

Every setting can be provided as a CLI argument or an environment variable. CLI arguments take precedence.

Flag	Env Variable	Default	Description
`-H`	`DUPLO_HOST`	--	DuploCloud portal URL (required)
`-t`	`DUPLO_TOKEN`	--	Authentication token (required)
`-T`	`DUPLO_TENANT`	--	Tenant name (optional but recommended)
`-tp`, `--transport`	`DUPLO_MCP_TRANSPORT`	`stdio`	Transport protocol (`stdio` or `http`)
`-mp`, `--port`	`DUPLO_MCP_PORT`	`8000`	Port for HTTP transport
`--resource-filter`	`DUPLO_MCP_RESOURCE_FILTER`	`.*`	Regex filter for resource names
`--command-filter`	`DUPLO_MCP_COMMAND_FILTER`	`.*`	Regex filter for command names
`--tool-mode`	`DUPLO_MCP_TOOL_MODE`	`compact`	Tool registration mode (`compact` or `expanded`)

All duploctl global arguments (-H, -t, -T, etc.) are also accepted and passed through to the DuploCloud client. The output flag (-o) is ignored as it does not apply in the MCP context. The query flag (-q) is available per tool call via the execute tool's query parameter.

Tool Modes

The --tool-mode flag controls how duploctl commands are exposed as MCP tools.

Expanded Mode

Registers one tool per resource+command combination, plus the config tool.

duploctl mcp --tool-mode expanded

Produces tools like tenant_create, tenant_find, service_list, etc. Each tool has its own input schema -- commands with Pydantic models (e.g. tenant_create) get full field-level schemas so the LLM sees every field name, type, and constraint.

Pro: Precise schemas, easy for the LLM to call correctly
Con: Many tools (potentially hundreds), may overwhelm tool selection

Use --resource-filter and --command-filter with expanded mode to keep the tool count manageable:

duploctl mcp --tool-mode expanded --resource-filter "tenant|service" --command-filter "list|find|create"

Compact Mode

Default. Registers five tools total, inspired by the duploctl bitbucket pipe.

duploctl mcp --tool-mode compact

Tool	Purpose
`resources`	List available resources (filtered)
`explain_resource`	List commands available on a resource
`explain_command`	Show arguments and body model schema for a specific command
`execute`	Run any duploctl command
`config`	Display current MCP server configuration

The intended LLM workflow:

resources -- get the list of available resources
explain_resource(resource) -- see what commands are available
explain_command(resource, command) -- see argument details and body schema
execute(resource, command, ...) -- run the command

The execute tool accepts name, args, body, query, and wait parameters. It dispatches through the same DuploClient path as the CLI, so model validation, filtering, and formatting all work the same way.

Pro: Only 5 tools, works well with tool-count-limited clients
Con: LLM needs multiple calls to discover schemas

Filtering

Filters use Python regex with fullmatch semantics -- the entire name must match the pattern.

Resource Filter

Expose only specific resource types:

# Only tenant tools
duploctl mcp --resource-filter "tenant"

# Tenant and service tools
duploctl mcp --resource-filter "tenant|service"

# Everything related to batch
duploctl mcp --resource-filter "batch_.*"

# All resources (default)
duploctl mcp --resource-filter ".*"

Via environment variable:

export DUPLO_MCP_RESOURCE_FILTER="tenant|service|s3"
duploctl mcp

Command Filter

Expose only specific operations across all resources:

# Read-only -- only list and find commands
duploctl mcp --command-filter "list|find"

# Only create and delete
duploctl mcp --command-filter "create|delete"

Combining Filters

Filters compose as an intersection. This exposes only list and find for tenant and service:

duploctl mcp \
  --resource-filter "tenant|service" \
  --command-filter "list|find"

Result: tenant_list, tenant_find, service_list, service_find.

MCP Client Configuration

stdio Transport (Default)

For most MCP clients (Claude Code, VS Code, etc.), use stdio transport. Add to your .mcp.json (project root) or .vscode/mcp.json:

{
  "mcpServers": {
    "duploctl": {
      "command": "duploctl",
      "args": ["mcp"],
      "env": {
        "DUPLO_HOST": "https://your-portal.duplocloud.net",
        "DUPLO_TOKEN": "your-token",
        "DUPLO_TENANT": "your-tenant"
      }
    }
  }
}

HTTP Transport

For clients that connect over HTTP (persistent server):

duploctl mcp --transport http

{
  "mcpServers": {
    "duploctl": {
      "url": "http://localhost:8000/mcp",
      "type": "http"
    }
  }
}

With Filters

{
  "mcpServers": {
    "duploctl": {
      "command": "duploctl",
      "args": ["mcp", "--resource-filter", "tenant|service"],
      "env": {
        "DUPLO_HOST": "https://your-portal.duplocloud.net",
        "DUPLO_TOKEN": "your-token",
        "DUPLO_TENANT": "your-tenant"
      }
    }
  }
}

Custom Tools and Routes

The @custom_tool and @custom_route decorators let you add ad-hoc tools and HTTP routes that receive a Ctx object with the DuploCloud client and server config injected.

from duplocloud.mcp.ctx import Ctx, custom_tool, custom_route
from starlette.requests import Request
from starlette.responses import JSONResponse

# A plain function that does the work
def get_status(ctx: Ctx) -> dict:
    tenants = ctx.duplo.load("tenant").list()
    return {
        "tenant_count": len(tenants),
        "tools": ctx.tools,
    }

# Expose as an MCP tool
@custom_tool(name="status", description="Get environment status.")
def status_tool(ctx: Ctx) -> dict:
    return get_status(ctx)

# Expose the same logic as an HTTP route
@custom_route("/status", methods=["GET"])
async def status_route(ctx: Ctx, request: Request):
    return JSONResponse(get_status(ctx))

The ctx parameter is injected automatically and hidden from the tool's input schema -- MCP clients never see it.

Mode Selector

Decorators accept an optional mode parameter to conditionally register based on server mode:

@custom_tool(name="debug_info", mode="debug")
def debug_info(ctx: Ctx) -> dict:
    """Only registered when the server runs in debug mode."""
    return {"config": ctx.config}

Endpoints

Endpoint	Method	Description
`/mcp`	POST	MCP protocol endpoint (StreamableHTTP)
`/health`	GET	Health check for load balancers
`/config`	GET	Live server configuration and registered tools

Docker

The Docker image uses duploctl mcp as its entrypoint with --transport http as the default CMD. Pass arguments at runtime to override:

# Default (http transport, compact mode)
docker run -e DUPLO_HOST=... -e DUPLO_TOKEN=... -e DUPLO_TENANT=... duplocloud-mcp

# stdio transport
docker run -e DUPLO_HOST=... -e DUPLO_TOKEN=... -e DUPLO_TENANT=... duplocloud-mcp --transport stdio

# Expanded mode with filters
docker run -e DUPLO_HOST=... -e DUPLO_TOKEN=... -e DUPLO_TENANT=... duplocloud-mcp \
  --tool-mode expanded --resource-filter "tenant|service"

Development

Project Structure

duplocloud/mcp/
  __main__.py        # Legacy entrypoint (use duploctl mcp instead)
  app.py             # FastMCP instance and health route
  compact_tools.py   # Compact mode tools (execute, explain, resources)
  config_display.py  # Built-in config tool and route
  ctx.py             # Ctx dataclass, @custom_tool, @custom_route
  server.py          # DuploCloudMCP resource plugin and lifecycle coordinator
  tools.py           # ToolRegistrar (duploctl -> MCP tool conversion)
  utils.py           # Docstring template resolution
tests/
  conftest.py        # Shared fixtures
  test_ctx.py        # Ctx, decorators, drain functions
  test_custom.py     # Context injection, register_custom, build_config
  test_filters.py    # Regex filter matching behavior
  test_modes.py      # Expanded and compact mode tests
  test_server.py     # DuploCloudMCP init, filter application, self-exclusion
  test_tools.py      # ToolRegistrar param building and wrapper construction

Running Tests

pip install -e ".[test]"
pytest

References

duploctl -- CLI and Python client for DuploCloud
Model Context Protocol -- MCP specification
FastMCP -- Framework powering this server
Keep a Changelog
Semantic Versioning

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github		.github
.vscode		.vscode
duplocloud/mcp		duplocloud/mcp
scripts		scripts
tests		tests
.devcontainer.json		.devcontainer.json
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yaml		docker-compose.yaml
pyproject.toml		pyproject.toml
test_error.py		test_error.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

DuploCloud MCP Server

Table of Contents

Features

Prerequisites

Installation

Quick Start

Configuration

Tool Modes

Expanded Mode

Compact Mode

Filtering

Resource Filter

Command Filter

Combining Filters

MCP Client Configuration

stdio Transport (Default)

HTTP Transport

With Filters

Custom Tools and Routes

Mode Selector

Endpoints

Docker

Development

Project Structure

Running Tests

References

About

Uh oh!

Releases 8

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

DuploCloud MCP Server

Table of Contents

Features

Prerequisites

Installation

Quick Start

Configuration

Tool Modes

Expanded Mode

Compact Mode

Filtering

Resource Filter

Command Filter

Combining Filters

MCP Client Configuration

stdio Transport (Default)

HTTP Transport

With Filters

Custom Tools and Routes

Mode Selector

Endpoints

Docker

Development

Project Structure

Running Tests

References

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages