Forem: Daniel Schroeder

Running Docker MCP Gateway on Linux (Without Docker Desktop)

Daniel Schroeder — Thu, 09 Apr 2026 18:46:30 +0000

Docker's MCP Toolkit is a great way to expose Model Context Protocol servers to AI clients like Claude, n8n, or Cursor. Out of the box it's designed for Docker Desktop on macOS and Windows — but what if you want to run it on a headless Linux server? A Raspberry Pi, a VPS, a home lab box?

This guide walks through setting it up from scratch on Linux (Debian/Ubuntu, arm64 or amd64), including secrets management, custom MCP server images, and a systemd service that starts automatically on boot.

This guide is based on getting it actually working on a Raspberry Pi 5 running
Debian 13. Several things that look like they should work on Linux don't — I'll
call those out explicitly so you don't waste time on the same dead ends.

What We're Building

A self-hosted MCP gateway that:

Runs any MCP server as a Docker container
Exposes them all behind a single HTTP endpoint with Bearer token auth
Starts automatically on boot via systemd

AI Client  →  http://your-server:8811/sse  →  docker-mcp gateway  →  MCP containers

Prerequisites

Linux host with Docker installed (Docker Engine, not Docker Desktop)
Your user in the docker group (sudo usermod -aG docker $USER)
SSH access if setting up remotely

Step 1 — Install the docker-mcp Binary

The docker mcp command is a Docker CLI plugin. On Linux you install it directly from the GitHub releases — no Docker Desktop needed.

# Create the CLI plugins directory
sudo mkdir -p /usr/local/lib/docker/cli-plugins

# Download the binary for your architecture
# arm64 (Raspberry Pi 4/5, Apple Silicon VMs):
sudo curl -fsSL \
  https://github.com/docker/mcp-gateway/releases/download/v0.41.0/docker-mcp-linux-arm64.tar.gz \
  | sudo tar -xz -C /usr/local/lib/docker/cli-plugins/

# amd64 (regular x86 server):
sudo curl -fsSL \
  https://github.com/docker/mcp-gateway/releases/download/v0.41.0/docker-mcp-linux-amd64.tar.gz \
  | sudo tar -xz -C /usr/local/lib/docker/cli-plugins/

sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-mcp

# Verify
docker mcp --version

Check the releases page for the latest version.

Step 2 — The docker-pass Workaround

This is the first Linux-specific gotcha. docker mcp CLI commands (like docker mcp server ls) expect a Docker CLI plugin named docker-pass. This binary ships with Docker Desktop on macOS but not on Linux, causing this error:

docker pass has not been installed

The fix: a small wrapper script that satisfies the Docker CLI plugin protocol and delegates to docker-credential-pass.

First, install docker-credential-pass:

# arm64:
sudo curl -fsSL \
  https://github.com/docker/docker-credential-helpers/releases/download/v0.9.5/docker-credential-pass-v0.9.5.linux-arm64 \
  -o /usr/local/bin/docker-credential-pass

# amd64:
sudo curl -fsSL \
  https://github.com/docker/docker-credential-helpers/releases/download/v0.9.5/docker-credential-pass-v0.9.5.linux-amd64 \
  -o /usr/local/bin/docker-credential-pass

sudo chmod +x /usr/local/bin/docker-credential-pass

Then create the wrapper plugin:

sudo tee /usr/local/lib/docker/cli-plugins/docker-pass > /dev/null << 'EOF'
#!/bin/bash
if [[ "$1" == "docker-cli-plugin-metadata" ]]; then
  echo '{"SchemaVersion":"0.1.0","Vendor":"Docker","Version":"v1.0.0","ShortDescription":"Docker Pass secrets helper"}'
  exit 0
fi
exec docker-credential-pass "$@"
EOF

sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-pass

Verify Docker recognizes it:

docker info --format '{{.ClientInfo.Plugins}}' | tr ',' '\n' | grep pass
# Should show: ...pass /usr/local/lib/docker/cli-plugins/docker-pass...

Note: This wrapper is only needed for docker mcp CLI commands. The gateway
itself uses a different mechanism for secrets — covered in Step 5.

Step 3 — Pull or Load Your MCP Images

Any Docker image that implements the MCP stdio protocol can be used as an MCP server.

Option A: Images from the official Docker MCP catalog

docker pull mcp/playwright:latest

Option B: Custom/private images

Transfer from another machine:

# On the source machine:
docker save mcp/my-server:latest | ssh your-linux-host "docker load"

Step 4 — Configure the Gateway

Create the config directory:

mkdir -p ~/.docker/mcp/catalogs

registry.yaml — which servers to enable

cat > ~/.docker/mcp/registry.yaml << 'EOF'
registry:
  playwright:
    ref: ""
  my-server:
    ref: ""
EOF

catalog.json — where to find catalog definitions

The gateway needs to know where your catalog files live. By default it only reads the official Docker MCP catalog. Register additional catalogs here:

cat > ~/.docker/mcp/catalog.json << 'EOF'
{
  "catalogs": {
    "docker-mcp": {
      "displayName": "Docker MCP Catalog",
      "url": "https://desktop.docker.com/mcp/catalog/v2/catalog.yaml"
    },
    "my-catalog": {
      "displayName": "My Custom Servers",
      "url": "/home/youruser/.docker/mcp/catalogs/my-catalog.yaml"
    }
  }
}
EOF

A catalog YAML for a custom server

The catalog defines how a server runs and which env vars it needs. List all env vars under secrets: — including non-sensitive ones like usernames.

Linux gotcha: The config: field in catalog YAMLs is not used for env var
injection on Linux. Everything must be in secrets: to be passed to containers.

registry:
  my-server:
    title: My MCP Server
    description: Does something useful
    image: mcp/my-server:latest
    type: server
    tools: []
    secrets:
      - name: my-server.api_key
        env: API_KEY
        description: API key for the service
      - name: my-server.username
        env: USERNAME
        description: Your username
name: my-catalog
displayName: My Catalog

Step 5 — Secrets

This is the second major Linux gotcha. docker mcp uses a secrets engine (se:// URIs) that is Docker Desktop-only and doesn't work on Linux. The docker mcp secret set command will fail with docker pass has not been installed even after you install the wrapper from Step 2.

The solution is the --secrets flag, which points the gateway at a plain env file:

# Create the secrets file
cat > ~/.docker/mcp/secrets.env << 'EOF'
my-server.api_key=your-api-key-here
my-server.username=your-username
EOF

# Restrict permissions — only your user can read it
chmod 600 ~/.docker/mcp/secrets.env

The key names map to the name field in the catalog's secrets: list.

Is this secure? The file is chmod 600 — readable only by your user, same as ~/.ssh/id_rsa. Anyone who can read it already has root or is you. If you want GPG encryption at rest, you can store sensitive values in pass and populate the file from it — but for an unattended service the threat model is the same either way.

Are secrets isolated between MCP servers? Yes, completely. The secrets file is never passed to or mounted into any container. The gateway reads it internally and uses it purely as a lookup table. When spawning each container it passes only the specific -e VAR=value flags declared in that server's catalog secrets: list. You can verify this with --dry-run --verbose — the docker run command for each server is logged in full, and you'll see that playwright gets zero secret env vars, while my-server only gets USERNAME and API_KEY. There is no way for one MCP server to access another's credentials.

Step 6 — Test the Gateway

Do a dry run first:

docker mcp gateway run \
  --dry-run \
  --verbose \
  --secrets ~/.docker/mcp/secrets.env \
  2>&1

You should see all your configured servers listed and their tools counted, with no Warning: Secret '...' not found lines. If warnings appear, check that the key names in secrets.env exactly match the name fields in your catalog YAML.

If everything looks good, start it live:

docker mcp gateway run \
  --transport sse \
  --port 8811 \
  --secrets ~/.docker/mcp/secrets.env

Step 7 — systemd Service

Create the service file:

sudo tee /etc/systemd/system/mcp-gateway.service > /dev/null << EOF
[Unit]
Description=Docker MCP Gateway
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=simple
User=$(whoami)
Environment=HOME=$HOME
ExecStart=/usr/local/lib/docker/cli-plugins/docker-mcp gateway run \\
  --transport sse \\
  --port 8811 \\
  --secrets $HOME/.docker/mcp/secrets.env
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

Set a stable Bearer token that survives restarts:

sudo mkdir -p /etc/systemd/system/mcp-gateway.service.d

TOKEN=$(openssl rand -hex 32)
echo "Save this token: $TOKEN"

sudo tee /etc/systemd/system/mcp-gateway.service.d/token.conf > /dev/null << EOF
[Service]
Environment=MCP_GATEWAY_AUTH_TOKEN=$TOKEN
EOF

Without this, the gateway generates a new random token on every start — which means reconfiguring every client after each restart.

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable mcp-gateway.service
sudo systemctl start mcp-gateway.service

Check it's running:

sudo systemctl status mcp-gateway.service
journalctl -u mcp-gateway.service -f

Connecting a Client

The gateway runs on port 8811 with SSE transport:

URL:   http://your-server:8811/sse
Auth:  Authorization: Bearer <your-token>

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "my-gateway": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://your-server:8811/sse",
        "--header",
        "Authorization: Bearer <your-token>",
        "--allow-http",
        "--transport",
        "sse-only"
      ]
    }
  }
}

Two flags are required here that aren't obvious:

--allow-http — mcp-remote blocks non-HTTPS URLs by default
--transport sse-only — the default http-first strategy sends a POST that the gateway rejects with sessionid must be provided

Troubleshooting

`docker pass has not been installed`

The docker-pass CLI plugin wrapper is missing or not executable. Re-check Step 2.

`Warning: Secret '...' not found`

The key name in secrets.env doesn't match the name field in the catalog YAML, or you forgot to pass --secrets to the gateway. Check with:

docker mcp gateway run --dry-run --verbose --secrets ~/.docker/mcp/secrets.env 2>&1 | grep Warning

Server shows 0 tools in dry-run but works live

Some servers need the actual secrets present to respond to tool listing. This is normal — the gateway still starts them correctly at runtime.

`cannot use --port with --transport=stdio`

You must specify --transport sse when using --port. The default transport is stdio (for direct client connections), not HTTP.

`sessionid must be provided` in mcp-remote

Add --transport sse-only to the mcp-remote args. The default transport strategy tries Streamable HTTP first, which the gateway doesn't support.

Keeping Things Updated

Upgrade docker-mcp

VERSION=v0.41.0  # replace with latest
ARCH=arm64       # or amd64

sudo curl -fsSL \
  https://github.com/docker/mcp-gateway/releases/download/$VERSION/docker-mcp-linux-$ARCH.tar.gz \
  | sudo tar -xz -C /usr/local/lib/docker/cli-plugins/

sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-mcp
sudo systemctl restart mcp-gateway.service

Update a custom MCP image

docker save mcp/my-server:latest | ssh your-linux-host "docker load"
ssh your-linux-host "sudo systemctl restart mcp-gateway.service"

Summary

The key differences from macOS Docker Desktop:

Concern	macOS (Docker Desktop)	Linux (headless)
`docker-mcp` binary	Bundled with Docker Desktop	Downloaded from GitHub releases
`docker-pass` plugin	Proprietary binary	Wrapper script → `docker-credential-pass`
Secrets injection	`docker mcp secret set` + keychain	`--secrets <env-file>` (chmod 600)
Auto-start	Docker Desktop	systemd service
Transport	stdio or SSE	SSE with `--transport sse`
mcp-remote	Default settings work	Needs `--allow-http --transport sse-only`

Everything else — catalog YAMLs, registry.yaml, the docker mcp CLI — works identically between macOS and Linux once the above pieces are in place.

Correctly defining CDK dependencies in L3 constructs

Daniel Schroeder — Mon, 28 Dec 2020 21:25:17 +0000

When creating L3 constructs for the AWS CDK, the easiest thing to get wrong is defining dependencies. And with wrong dependency definitions you make it hard to impossible to use your package. This post will show how to correctly define CDK dependencies.

As a CDK user, you already know, all CDK core packages have to be of the same version or you will get cryptic errors such as:

unable to determine cloud assembly output directory. Assets must be defined indirectly within a "Stage" or an "App" scope

Types of property 'node' are incompatible... Types have separate declarations of a private property 'host'.

So what you want to avoid when publishing L3 constructs, is to directly depend your package on any version of the core CDK packages. Still, this is the case in almost every L3 construct I have seen. I'm assuming this is because the core packages themselves do it like this and developers learn from reading code.

Usually you find packages having either exact or caret versions in their dependencies. Also, in most cases, these definitions are accompanied with the same items in the peerDependencies. Let's analyze these two setups and what the result for the end-user is going to be:

Dependencies with caret version

{
  ...
  "dependencies": {
    "@aws-cdk/aws-lambda": "^1.23.0"
  },
  "peerDependencies": {
    "@aws-cdk/aws-lambda": "^1.23.0"
  }
  ...
}

The caret definition means, install the latest minor compatible to the given version. That is everything < 2.0.0. So until CDK 2 drops, this will install the very latest package for aws-lambda.

The end-user now can only install your package, when all application dependencies refer to the latest CDK packages as well. If CDK 1.70.0 or any other older version is used, there is no way the user can install your package without causing incompatibility between core packages. The solution from user perspective is to upgrade the CDK and deal with the potentially introduced breaking changes.

Dependencies with exact version

{
  ...
  "dependencies": {
    "@aws-cdk/aws-lambda": "1.80.0"
  },
  "peerDependencies": {
    "@aws-cdk/aws-lambda": "1.80.0"
  }
  ...
}

A package with this dependencies definition of course is only compatible with exactly one version of the CDK. This means your users cannot upgrade the CDK without upgrading your package and vice versa. To make your package usable by future CDK versions you need to release new versions of your package for every CDK release. Most probably you do this automated. And either you have a mapping between CDK version and your package version in your docs or you use the same exact version as the upstream packages, which renders the information (semver) of your version string useless. How do you progress your own code? How do you communicate bug-fixes or breaking changes? And let's not forget, you waste computational resources for compiling, transferring and storing your build artifacts without actual change.

The problem though, is not the format of your dependency definition (exact vs. caret) - the problem simply is: You have dependencies.

And as simple as that problem statement, is the solution: Just don't.

Instead, list them in the peerDependencies and devDependencies. You should use caret versions, defining the minimum version required by your package. Typically this should be the version when all your CDK dependencies went stable. If you don't know or don't care, use ^1.0.0.

{
  ...
  "devDependencies": {
    "@aws-cdk/aws-lambda": "^1.0.0"
  },
  "peerDependencies": {
    "@aws-cdk/aws-lambda": "^1.0.0"
  }
  ...
}

You need them in the devDependencies to build your package with jsii and you need them in the peerDependencies to let the user know what packages need to be installed along with your package.

Now, when a user installs your package, what happens depends on the used language and package manager. Either way, the user needs to define the peer-dependencies as dependencies of the application, e.g. in the package.json or requirements.txt.

npm version < 6 will warn about missing peer dependencies:

npm WARN cdk-awesome-package@1.2.3 requires a peer of @aws-cdk/aws-lambda@^1.0.0 but none was installed.

The same goes for yarn:

warning " > cdk-awesome-package@1.2.3" has unmet peer dependency "@aws-cdk/aws-lambda@^1.0.0".

In npm 6 for some reason this is missing and the user will only know about the missing dependency when the application is ran. That's fine though, the error message is clear about what package needs to be installed. An entry in the package.json needs to be made:

{
  ...
  "dependencies": {
    "@aws-cdk/aws-lambda": "1.70.0",
    "cdk-awesome-package": "^1.2.3"
  },
  ...
}

Starting with npm version 7 the handling of peer dependencies has changed - they will be automatically installed and you cannot override the version in the dependencies section. Instead the user now needs to add it to the overrides section.

{
  "dependencies": {
    "cdk-awesome-package": "^1.2.3"
  },
  "overrides": {
    "@aws-cdk/aws-lambda": "1.70.0",
  }
}

Alternatively the user can also just switch back to the old behaviour by setting legacy-peer-deps=true in the .npmrc.

All other languages supported by jsii don't support peer dependencies. For these languages they are converted to normal dependencies. pip correctly interprets the caret version definition of ^1.0.0 and in return you would install the latest version. For the dotnet package, jsii converted ^1.0.0 to 1.0.0... which in the end really doesn't matter. Because this can and has to be overridden by the user anyway.

With pip the user can override the version of dependencies by simply adding them to the applications requirements.txt or setup.py, e.g.:

aws-cdk-aws-lambda==1.70.0
cdk-awesome-package>=1.2.3

In C# the user can also override the version in the project file, e.g.

<ItemGroup>
  <PackageReference Include="Amazon.CDK.AWS.LAMBDA" Version="1.70.0" />
  <PackageReference Include="CDK.Awesome.Package" Version="1.*" />
</ItemGroup>

I haven't checked Java but I assume the same can be archived in a gradle file.

And there you go. A CDK L3 construct working with any version of core CDK packages.

Update 2021/04/17

But what about breaking changes?

I've seen some developers are automatically releasing new versions of their L3 constructs for every new CDK release for the reason of compatibility, especially when experimental CDK components are involved. I strongly disagree with this approach.

First of all, if an L3 uses experimental features, then the L3, as a consequence, is experimental. It should be used with caution and breaking changes should be expected with every minor update. Most likely it also should not be used in production, unless the user knows what she/he's doing and pays the proper attention. Using experimental features means, the user might not be able to upgrade without destroying/recreating related infrastructure.

Next: Ensuring compatibility with future versions of a framework is not the responsibility of a package author. If there are breaking changes, of course things will fail. The same would be true if the user directly used experimental CDK features. The responsibility of catching these is not with the L3 author, but with the user of the construct. Every user needs to be aware that the smallest change needs testing. Of course, when there are package changes, the app needs to be deployed in a test environment, ran with diff and ideally even has proper jest tests in place, before it reaches your prod environment.

You cannot solve testing for the user. The best you can catch by building a package per CDK version is a change in the API signature. Maybe an option has been removed or renamed and therefore your code is not compatible and won't compile. The real danger though lies in functional changes, that make the code run, but behave differently. A very good example for this would be CDK version 1.75.0, which included the following change:

efs: keyId property uses the ARN instead of the keyId to support cross-account encryption key usage. The filesystem will be replaced.

This is the real danger with experimental packages and you cannot protect the user from this by building a new version of your package.

Also, what's exactly the benefit of building new packages for every release? You ensure it still builds. So what if it doesn't? Your build fails, you'll be notified by your action/workflow and you need to adjust the code to match the new API, because building new packages does not automagically fix the problem. Let's assume you're knee-deep involved in other projects or actual life and you don't have time to fix it for some time.
Consequence: No user will be able to upgrade the core CDK packages until you fixed your code and released a compatible package.

Now imagine you had not auto-built new packages but instead used my suggested best practice? The package will not be compatible with the latest CDK version.
Consequence: No user will be able to upgrade the core CDK packages until you fixed your code and released a compatible package.

The only difference would be, that you won't be notified by your failed pipeline/action and wouldn't be aware there is a breaking change. And this can easily be fixed by testing your package for new CDK releases.

So instead of building and publishing new packages for absolutely no reason, you should test your package against every new CDK release.

What about projen?

Since 1st of March 2021 you can set cdkDependenciesAsDeps: false in your .projenrc.js to prevent projen from adding the CDK packages as dependencies and only list them as peerDependencies.

Terraform workspace config organization

Daniel Schroeder — Wed, 20 Nov 2019 15:23:55 +0000

The suggested best practices for organizing configuration for multiple workspaces/environments is to call Terraform with -var-file=$env to include a specific tfvars file.

Of course this works. But it seems to be error prone if you allow to trigger an apply against any workspace with just any configuration:

terraform workspace select production
terraform apply -var-file=config/staging.tfvars

Furthermore this cannot be used in Terraform Cloud, where you have to specify workspace related vars in the workspace configuration itself:

There is no option for including tfvars per workspace.

Select config automatically based on the workspace

Unfortunately there is no functionality to automatically include a tfvars file based on the workspace name nor is there support for conditionally including tfvars files.

So you got to build something yourself. You can access the current workspace name via terraform.workspace. There are a couple of things you can do with this value.

Below are 3 solutions which all have the same exact outcome. The defined config is stored in local.config and can be access via local.config.ec2_instance_type etc.

All 3 solutions support default values, so you're not required to define every config option in every environment.

All examples are available in this repository.

1. Inline expressions to select correct config from a map

All config is held is a single file config.tf:

locals {
  configs = {

    _defaults = {
      ec2_instance_type = "t2.nano"
      regions           = ["us-east-1"]
    }

    dev = {} // use config from _defaults ^

    staging = {
      ec2_instance_type = "t2.medium"
      regions = [
        "us-east-1",
        "eu-central-1",
      ]
    }

    production = {
      ec2_instance_type = "t2.xlarge"
      regions = [
        "us-east-1",
        "us-west-2",
        "eu-central-1",
        "ap-east-1",
      ]
    }

  }

  config = merge(
    lookup(local.configs, "_defaults"),
    lookup(local.configs, terraform.workspace)
  )
}

Pros:

Straight forward

Cons:

Cannot split config into separate files. Therefore could quickly get hard to maintain and compare environment config.

2. Load config from YAML files

Directory structure:

.
├── config
│   ├── _defaults.yml
│   ├── dev.yml
│   ├── production.yml
│   └── staging.yml
├── config.tf
├── main.tf

Example content of config/production.yml:

---
ec2_instance_type: t2.xlarge

regions:
  - us-east-1
  - us-west-2
  - eu-central-1
  - ap-east-1

The config is loaded in config.yml:

data "local_file" "defaults" {
  filename = "${path.module}/config/_defaults.yml"
}

data "local_file" "config" {
  filename = "${path.module}/config/${terraform.workspace}.yml"
}

locals {
  config = merge(
    yamldecode(data.local_file.defaults.content),
    yamldecode(data.local_file.config.content)
  )
}

Pros:

Straight forward
Config for every environment resides in its own file

Cons:

No HCL expressions are possible in the config itself

3. Create a module per environment and return the config as an output

Directory structure:

.
├── config
│   ├── _defaults
│   │   └── outputs.tf
│   ├── dev
│   │   └── outputs.tf
│   ├── main.tf
│   ├── production
│   │   └── outputs.tf
│   └── staging
│       └── outputs.tf
├── main.tf

In every config/$env/outputs.tf a single output is defined like this:

config/_defaults/outputs.tf:

output "data" {
  value = {
    ec2_instance_type = "t2.nano"
    regions = [
      "us-east-1",
    ]
  }
}

config/dev/outputs.tf:

output "data" {
  value = {} // use config from _defaults
}

config/staging/outputs.tf:

output "data" {
  value = {
    ec2_instance_type = "t2.medium"
    regions = [
      "us-east-1",
      "eu-central-1",
    ]
  }
}

config/production/outputs.tf:

output "data" {
  value = {
    ec2_instance_type = "t2.xlarge"
    regions = [
      "us-east-1",
      "us-west-2",
      "eu-central-1",
      "ap-east-1",
    ]
  }
}

Since you cannot use variables in a module source parameter all 4 modules have to be defined in every environment. Furthermore you cannot directly access a module by name when the name is not hardcoded, so you need to additionally create a mapping like so:

config/main.tf:

module "_defaults" {
  source = "./_defaults"
}

module "dev" {
  source = "./dev"
}

module "staging" {
  source = "./staging"
}

module "production" {
  source = "./production"
}

locals {
  data_map = {
    dev        = module.dev.data,
    staging    = module.staging.data,
    production = module.production.data,
  }
}

output "data" {
  value = merge(
    module._defaults.data,
    lookup(local.data_map, terraform.workspace)
  )
}

In the main.tf then the module needs to be loaded and for convenience the output gets registered as a local value:

module "config" {
  source = "./config"
}

locals {
  config = module.config.data
}

Pros:

Config for every environment resides in its own file

Cons:

Complex setup

Conclusion

Using modules as config provider seems to be the best solution, as you can split the configuration into separate files which supports HCL expressions. The setup though is complex and requires some additional boilerplate code for every additional environment.

If you have no need for HCL expressions, the YAML solution seems to be nice as it is easy to setup and IMHO is very readable to humans.

Forem: Daniel Schroeder

Running Docker MCP Gateway on Linux (Without Docker Desktop)

What We're Building

Prerequisites

Step 1 — Install the docker-mcp Binary

Step 2 — The docker-pass Workaround

Step 3 — Pull or Load Your MCP Images

Option A: Images from the official Docker MCP catalog

Option B: Custom/private images

Step 4 — Configure the Gateway

registry.yaml — which servers to enable

catalog.json — where to find catalog definitions

A catalog YAML for a custom server

Step 5 — Secrets

Step 6 — Test the Gateway

Step 7 — systemd Service

Connecting a Client

Claude Desktop

Troubleshooting

docker pass has not been installed

Warning: Secret '...' not found

Server shows 0 tools in dry-run but works live

cannot use --port with --transport=stdio

sessionid must be provided in mcp-remote

Keeping Things Updated

Upgrade docker-mcp

Update a custom MCP image

Summary

Correctly defining CDK dependencies in L3 constructs

Update 2021/04/17

Terraform workspace config organization

Select config automatically based on the workspace

1. Inline expressions to select correct config from a map

2. Load config from YAML files

3. Create a module per environment and return the config as an output

Conclusion

`docker pass has not been installed`

`Warning: Secret '...' not found`

`cannot use --port with --transport=stdio`

`sessionid must be provided` in mcp-remote