Skip to content

docker-mcp-setup.md

Latest commit

 

History

History
426 lines (304 loc) · 10 KB

docker-mcp-setup.md

File metadata and controls

426 lines (304 loc) · 10 KB
Raw

Docker MCP Setup Guide

EN

Guide for setting up Docker-based MCP (Model Context Protocol) servers with AIOX.

Version: 2.1.0 Last Updated: 2026-01-28

Prerequisites

Before setting up Docker MCP, ensure you have:

  • Docker Desktop installed and running
  • Node.js 18+ installed
  • AIOX project initialized
  • API keys for desired MCP services (EXA, Apify, etc.)

Installation

Step 1: Install Docker MCP Toolkit

# Install the Docker MCP Toolkit
docker mcp install

# Verify installation
docker mcp --version

Step 2: Initialize MCP Configuration

# Create global MCP structure
aiox mcp setup

This creates:

  • ~/.aiox/mcp/ - MCP configuration directory
  • ~/.aiox/mcp/global-config.json - Main config file
  • ~/.aiox/mcp/servers/ - Individual server configs
  • ~/.aiox/credentials/ - Secure credential storage

Step 3: Add MCP Servers

# Add servers from templates
aiox mcp add context7
aiox mcp add exa
aiox mcp add github

Configuration

MCP Architecture

AIOX uses Docker MCP Toolkit as the primary MCP infrastructure:

┌─────────────────────────────────────────────────────────┐
│                    Claude Code                           │
│                         │                                │
│    ┌────────────────────┼────────────────────┐          │
│    │                    │                    │          │
│    ▼                    ▼                    ▼          │
│ playwright      docker-gateway           native tools   │
│ (direct)        (container MCPs)         (Read, Write)  │
│                         │                                │
│              ┌──────────┼──────────┐                    │
│              ▼          ▼          ▼                    │
│            EXA     Context7     Apify                   │
│         (search)   (docs)     (scraping)               │
└─────────────────────────────────────────────────────────┘

Direct in Claude Code (global ~/.claude.json)

MCP Purpose
playwright Browser automation, screenshots, web testing
desktop-commander Docker container operations via docker-gateway

Inside Docker Desktop (via docker-gateway)

MCP Purpose
EXA Web search, research, company/competitor analysis
Context7 Library documentation lookup
Apify Web scraping, Actors, social media data extraction

Configuration Files

global-config.json:

{
  "version": "1.0",
  "servers": {
    "context7": {
      "type": "sse",
      "url": "https://mcp.context7.com/sse",
      "enabled": true
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "${EXA_API_KEY}"
      },
      "enabled": true
    }
  },
  "defaults": {
    "timeout": 30000,
    "retries": 3
  }
}

Available MCPs

Context7 (Documentation Lookup)

# Add Context7
aiox mcp add context7

# Usage
mcp__context7__resolve-library-id
mcp__context7__query-docs

Use for:

  • Library documentation lookup
  • API reference for packages/frameworks
  • Getting up-to-date docs for dependencies

EXA (Web Search)

# Add EXA
aiox mcp add exa

# Set API key
export EXA_API_KEY="your-api-key"

# Usage
mcp__exa__web_search_exa
mcp__exa__get_code_context_exa

Use for:

  • Web searches for current information
  • Research and documentation lookup
  • Company and competitor research
  • Finding code examples online

Apify (Web Scraping)

# Add Apify
aiox mcp add apify

# Set API token
export APIFY_TOKEN="your-token"

# Usage
mcp__docker-gateway__search-actors
mcp__docker-gateway__call-actor

Use for:

  • Web scraping for social media (Instagram, TikTok, LinkedIn)
  • Extracting data from e-commerce sites
  • Automated data collection from any website
  • RAG-enabled web browsing for AI context

GitHub (API Integration)

# Add GitHub
aiox mcp add github

# Set token
export GITHUB_TOKEN="your-token"

Use for:

  • GitHub API operations
  • Repository management
  • PR and issue handling

Playwright (Browser Automation)

# Add Playwright
aiox mcp add puppeteer

Use for:

  • Browser automation
  • Taking screenshots of web pages
  • Interacting with websites
  • Web scraping and testing

CLI Commands

Setup Commands

# Initialize global MCP configuration
aiox mcp setup

# Force recreate (backup existing)
aiox mcp setup --force

Server Management

# Add server from template
aiox mcp add <server-name>

# Add with custom config
aiox mcp add custom-server --config='{"command":"npx","args":["-y","package"]}'

# Remove server
aiox mcp remove <server-name>

# Enable/disable servers
aiox mcp enable <server-name>
aiox mcp disable <server-name>

Status and Listing

# List configured servers
aiox mcp list

# Show detailed status
aiox mcp status

# Sync to project
aiox mcp sync

Environment Variables

Setting Variables

macOS/Linux:

export EXA_API_KEY="your-api-key"
export GITHUB_TOKEN="your-github-token"
export APIFY_TOKEN="your-apify-token"

Windows (PowerShell):

$env:EXA_API_KEY = "your-api-key"
$env:GITHUB_TOKEN = "your-github-token"
$env:APIFY_TOKEN = "your-apify-token"

Persistent Variables

Add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.profile):

export EXA_API_KEY="your-api-key"
export GITHUB_TOKEN="your-github-token"
export APIFY_TOKEN="your-apify-token"

Secure Credential Storage

# Add credential
aiox mcp credential set EXA_API_KEY "your-api-key"

# Get credential
aiox mcp credential get EXA_API_KEY

# List credentials (masked)
aiox mcp credential list

Troubleshooting

Common Issues

Issue Solution
Permission denied Run terminal as Administrator (Windows) or use sudo
Server not starting Check command and args, verify package installed
Environment variable not found Set variable or use credentials storage
Timeout errors Increase timeout in config
Connection refused Check URL and network access

Docker MCP Secrets Bug (Dec 2025)

Issue: Docker MCP Toolkit's secrets store (docker mcp secret set) and template interpolation ({{...}}) do NOT work properly. Credentials are not passed to containers.

Symptoms:

  • docker mcp tools ls shows "(N prompts)" instead of "(N tools)"
  • MCP server starts but fails authentication
  • Verbose output shows -e ENV_VAR without values

Workaround: Edit ~/.docker/mcp/catalogs/docker-mcp.yaml directly:

{ mcp-name }:
  env:
    - name: API_TOKEN
      value: 'actual-token-value-here'

Example - Apify:

apify-mcp-server:
  env:
    - name: TOOLS
      value: 'actors,docs,apify/rag-web-browser'
    - name: APIFY_TOKEN
      value: 'apify_api_xxxxxxxxxxxxx'

Note: This exposes credentials in a local file. Secure file permissions and never commit this file.

Common Fixes

# Reset global config
aiox mcp setup --force

# Clear cache
rm -rf ~/.aiox/mcp/cache/*

# Verify config
aiox mcp status --verbose

# Test server manually
npx -y @modelcontextprotocol/server-github

MCP Governance

Important: All MCP infrastructure management is handled exclusively by the DevOps Agent (@devops / Felix).

Operation Agent Command
Search MCP catalog DevOps *search-mcp
Add MCP server DevOps *add-mcp
List enabled MCPs DevOps *list-mcps
Remove MCP server DevOps *remove-mcp
Setup Docker MCP DevOps *setup-mcp-docker

Other agents (Dev, Architect, etc.) are MCP consumers, not administrators. If MCP management is needed, delegate to @devops.

Tool Selection Priority

Always prefer native Claude Code tools over MCP servers:

Task USE THIS NOT THIS
Read files Read tool docker-gateway
Write files Write / Edit tools docker-gateway
Run commands Bash tool docker-gateway
Search files Glob tool docker-gateway
Search content Grep tool docker-gateway
List directories Bash(ls) or Glob docker-gateway

When to Use docker-gateway

Only use docker-gateway when:

  1. User explicitly says "use docker" or "use container"
  2. User explicitly mentions "Desktop Commander"
  3. Task specifically requires Docker container operations
  4. Accessing MCPs running inside Docker (EXA, Context7)
  5. User asks to run something inside a Docker container

Related Documentation

Synkra AIOX Docker MCP Setup Guide v4.2.11