Add Custom MCP Gateway example + servers (brave, wikipedia, postgres) and CI

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+    branches: [ "**" ]
+
+jobs:
+  lint:
+    name: Lint Markdown and YAML
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Markdown Lint
+        uses: avto-dev/markdown-lint@v1
+        with:
+          config: .markdownlint.yaml
+          args: |
+            **/*.md
+
+      - name: YAML Lint
+        uses: ibiqlik/action-yamllint@v3
+        with:
+          file_or_dir: .
+          config_file: .yamllint
+          strict: true

.github/workflows/compose-ci.yml

@@ -0,0 +1,46 @@
+name: Compose CI
+
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+    branches: [ "**" ]
+
+jobs:
+  compose-validate:
+    name: Compose config validation (custom-mcp)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Docker version
+        run: docker version
+      - name: Compose config
+        run: |
+          docker compose -f custom-mcp/compose.yaml -f custom-mcp/compose.ci.yaml config
+        working-directory: agents/compose-for-agents
+
+  e2e-health:
+    name: E2E health check (custom-mcp)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Start stack
+        run: |
+          docker compose -f custom-mcp/compose.yaml -f custom-mcp/compose.ci.yaml up -d
+        working-directory: agents/compose-for-agents
+      - name: Wait for health
+        run: |
+          for i in $(seq 1 30); do
+            if curl -fsS http://localhost:8811/health; then
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "Gateway health check failed" >&2
+          docker compose -f custom-mcp/compose.yaml -f custom-mcp/compose.ci.yaml logs || true
+          exit 1
+        working-directory: agents/compose-for-agents
+      - name: Teardown
+        if: always()
+        run: docker compose -f custom-mcp/compose.yaml -f custom-mcp/compose.ci.yaml down -v --remove-orphans
+        working-directory: agents/compose-for-agents

.gitignore

@@ -5,3 +5,5 @@
 /.cursor/
 **/init-secrets.sh
 **/secret.openai-api-key
+**/.mcp.env
+**/postgres_url

README.md

@@ -52,6 +52,7 @@ The demos support using OpenAI models instead of running models locally with Doc
 | [ADK](https://github.com/google/adk-python) Sock Store Agent | Multi-Agent | qwen3 | MongoDb, Brave, Curl,  | [./adk-sock-shop](./adk-sock-shop/) | [compose.yaml](./adk-sock-shop/compose.yaml) |
 | [Langchaingo](https://github.com/tmc/langchaingo) DuckDuckGo Search | Single Agent | gemma3 | duckduckgo | [./langchaingo](./langchaingo) | [compose.yaml](./langchaingo/compose.yaml) |
 | [MinionS](https://github.com/HazyResearch/minions) Cost-Efficient Local-Remote Collaboration | Local-Remote Protocol | qwen3(local), gpt-4o(remote) |  | [./minions](./minions) | [docker-compose.minions.yml](https://github.com/HazyResearch/minions/blob/main/apps/minions-docker/docker-compose.minions.yml) |
+| Custom MCP Gateway (this repo) | Gateway + Tools | none | duckduckgo, github-official (extensible) | [./custom-mcp](./custom-mcp) | [compose.yaml](./custom-mcp/compose.yaml) |
 
 ## License
 

custom-mcp/README.md

@@ -0,0 +1,48 @@
+# Custom MCP Gateway Stack
+
+This example wires a Docker MCP Gateway with a flexible set of MCP servers and secrets loaded from a `.mcp.env` file.
+
+Prerequisites
+- Docker Desktop 4.43+ or Docker Engine with Compose v2.38.1+
+- Optional: Docker Model Runner if you plan to use local models
+
+Setup
+1. cd custom-mcp
+2. cp mcp.env.example .mcp.env
+3. Fill in required secrets (e.g., GITHUB_TOKEN for `github-official`).
+
+Run
+- Start the stack:
+  docker compose up --build
+
+- The gateway will listen on port 8811. A health endpoint is available at:
+  http://localhost:8811/health
+
+Modify servers
+- Edit compose.yaml and add or remove `--servers=...` entries on the mcp-gateway service.
+- If a server needs credentials, add them to `.mcp.env` and reference via `--secrets=...` if required.
+
+Included servers & secrets
+- duckduckgo: No secret required (optional app name via DUCKDUCKGO_APP_NAME)
+- github-official: Requires GITHUB_TOKEN in .mcp.env
+- brave: Requires BRAVE_API_KEY in .mcp.env
+- wikipedia-mcp: No secret required
+- postgres with SQL query tool:
+  - Create a file named `postgres_url` in this directory containing the DSN, e.g.
+    postgres://user:password@host:5432/dbname
+  - This is mounted as a secret named `database-url` and used by the gateway.
+
+Notes
+- The example includes a minimal curl-based `mcp-client` container that checks gateway health.
+- To integrate with an agent, set its MCP server URL to the gateway endpoint, e.g. `http://mcp-gateway:8811/sse` for SSE transport.
+
+Agent integration patterns
+- LangGraph/LangChain: set MCP endpoint env (e.g., MCP_SERVER_URL=http://mcp-gateway:8811/sse) in your agent container.
+- Agno/ADK: point to MCP gateway URL (SSE or streaming) as shown in existing examples in this repo.
+- UI frontends (e.g., Vercel AI SDK demo): configure your backend/agent server to call the gateway; avoid exposing gateway publicly.
+
+Troubleshooting
+- 401/403 from servers: ensure tokens (e.g., GITHUB_TOKEN, BRAVE_API_KEY) are present in .mcp.env and mapped via --secrets if required.
+- Postgres errors: verify postgres_url content is a valid DSN and the DB is reachable from the gateway container.
+- Port already in use: change ports mapping under mcp-gateway, e.g., "8812:8811", and curl http://localhost:8812/health.
+- CI differences: CI uses compose.ci.yaml override with only duckduckgo and wikipedia (no secrets, no Docker API socket).

custom-mcp/Taskfile.yaml

@@ -0,0 +1,27 @@
+version: "3"
+
+tasks:
+  up:
+    desc: Start custom MCP stack
+    cmds:
+      - docker compose up --build
+    dir: .
+
+  down:
+    desc: Stop and remove containers
+    cmds:
+      - docker compose down -v --remove-orphans
+    dir: .
+
+  build:
+    desc: Build images
+    cmds:
+      - docker compose build
+    dir: .
+
+  clean:
+    desc: Clean everything
+    cmds:
+      - docker compose down -v --remove-orphans
+      - docker builder prune -f
+    dir: .

custom-mcp/compose.ci.yaml

@@ -0,0 +1,12 @@
+services:
+  mcp-gateway:
+    # In CI, avoid using Docker API socket and any external secrets.
+    # Only enable servers that require no credentials.
+    use_api_socket: false
+    ports:
+      - "8811:8811"
+    command:
+      - --transport=sse
+      - --servers=duckduckgo
+      - --servers=wikipedia-mcp
+    secrets: []

custom-mcp/compose.yaml

@@ -0,0 +1,47 @@
+services:
+  # Minimal test client to verify the MCP Gateway is reachable.
+  mcp-client:
+    image: curlimages/curl:8.11.1
+    depends_on:
+      - mcp-gateway
+    command: ["/bin/sh", "-lc", "curl -sS http://mcp-gateway:8811/health || sleep 3600"]
+
+  mcp-gateway:
+    # Secures and launches MCP servers via the Docker API socket
+    image: docker/mcp-gateway:latest
+    use_api_socket: true
+    ports:
+      - "8811:8811"
+    command:
+      # switch between streaming or sse depending on your agent
+      - --transport=sse
+      # secrets can be provided multiple times and referenced per server
+      - --secrets=docker-desktop:/run/secrets/mcp_secret
+      # For Postgres DSN
+      - --secrets=/run/secrets/database-url
+      # Enable the servers you need. Add/remove as desired.
+      # Built-in servers supported by gateway include e.g. duckduckgo, github-official, postgres
+      - --servers=duckduckgo
+      - --servers=github-official
+      - --servers=brave
+      - --servers=wikipedia-mcp
+      # Postgres server and SQL tool (requires database-url secret file)
+      - --servers=postgres
+      - --tools=query
+    secrets:
+      - mcp_secret
+      - database-url
+
+# Example model configuration if you want to co-run with Docker Model Runner
+# and point an agent to it. Not strictly required for MCP Gateway testing.
+# models:
+#   qwen3-small:
+#     model: ai/qwen3:8B-Q4_0
+#     context_size: 15000
+
+# Mount the secrets file used by MCP servers
+secrets:
+  mcp_secret:
+    file: ./.mcp.env
+  database-url:
+    file: ./postgres_url

custom-mcp/mcp.env.example

@@ -0,0 +1,9 @@
+# Copy this file to .mcp.env and fill in the values you need
+# Common MCP servers
+GITHUB_TOKEN=
+DUCKDUCKGO_APP_NAME=docker-compose-for-agents
+BRAVE_API_KEY=
+
+# Postgres DSN is read from a separate secret file named "postgres_url" in this directory.
+# Example content:
+# postgres://user:password@host:5432/dbname