Skip to content

Commit b73b498

Browse files
mikesir87mikesir87
committed
Initial commit
0 parents  commit b73b498

12 files changed

+722
-0
lines changed

‎.github/workflows/deploy-labspace-compose.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Build and Push Docker Image
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
build-and-push:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout code
13+
uses: actions/checkout@v4
14+
15+
# Ensure Compose v2.39.3+ is available (includes bug fixes for publishing)
16+
# Can remove this action once default runners include it
17+
- name: Set up Docker Compose
18+
uses: docker/setup-compose-action@v1
19+
with:
20+
version: v2.39.3
21+
22+
- name: Log in to DockerHub
23+
uses: docker/login-action@v3
24+
with:
25+
username: ${{ secrets.DOCKERHUB_USERNAME }}
26+
password: ${{ secrets.DOCKERHUB_TOKEN }}
27+
28+
- name: Publish Compose file
29+
run: |
30+
docker compose -f oci://dockersamples/labspace -f .labspace/compose.override.yaml publish $DOCKERHUB_USERNAME/labspace-mcp-gateway --with-env -y
31+
env:
32+
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/compose.yaml
2+
.env

‎.labspace/01-introduction.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Introduction
2+
3+
👋 Welcome to the **Docker MCP Gateway** lab! During this lab, you will learn to do the following:
4+
5+
- Learn about the Docker MCP Gateway
6+
- Learn how to run the MCP Gateway with a simple MCP server
7+
- Securely inject secrets into MCP servers
8+
- Filter tools to reduce noise and save tokens
9+
- Learn how to connect the MCP Gateway to your application using popular agentic frameworks
10+
11+
Throughout this session, you'll also learn how to use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to interact with MCP servers and debug/troubleshoot potential issues.
12+
13+
14+
15+
## 🙋 What is MCP again?
16+
17+
**Model Context Protocol (MCP)** standardizes how AI applications connect to external data sources and tools.
18+
19+
It provides the ability to package and distribute common tools you might need in AI workflows. Examples might include:
20+
21+
- Retrieve data from GitHub about open issues or pull requests
22+
- Lookup customer or subscription information from Stripe
23+
- Create a Notion page with summarized details
24+
- Send an email using Resent
25+
- Or more!
26+
27+
By using MCP, it allows you to easily extend or add capabilities to your AI applications.
28+
29+
```mermaid
30+
flowchart LR
31+
AI[AI Client] --> S1[DuckDuckGo MCP Server]
32+
S1 --> DuckDuckgo[DuckDuckGo APIs]
33+
S1 --> Content[Arbitrary web content]
34+
AI --> S2[GitHub MCP Server]
35+
S2 --> GitHub[GitHub APIs]
36+
```
37+
38+
## Why a MCP Gateway?
39+
40+
When running MCP servers, you often want a single connection point for your application to send all MCP requests. This allows you to **audit** and **log** more easily, **configure** more securely, and more.
41+
42+
By using a MCP Gateway, your application also needs only a single MCP connection, making your architecture look similar to the following:
43+
44+
```mermaid
45+
flowchart LR
46+
AI[AI Client] --> GW[MCP Gateway]
47+
48+
subgraph "MCP Gateway"
49+
GW --> S1[DuckDuckGo MCP Server]
50+
GW --> S2[GitHub MCP Server]
51+
end
52+
53+
S1 --> DuckDuckgo[DuckDuckGo APIs]
54+
S1 --> Content[Arbitrary web content]
55+
S2 --> GitHub[GitHub APIs]
56+
```
57+
58+
The **[Docker MCP Gateway](https://github.com/docker/mcp-gateway)** is an open-source gateway that makes it simple, safe, and secure to run MCP servers inside containers.
59+
60+
Docker additionally provides a **[MCP Catalog](https://hub.docker.com/mcp)**, which is a collection of containerized MCP servers that are easy to get up and going.
61+
62+
With that, let's get started by starting the MCP Gateway with a simple MCP server!

‎.labspace/02-adding-a-simple-mcp-server.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Running a simple MCP Server
2+
3+
The **[DuckDuckGo MCP server](https://hub.docker.com/mcp/server/duckduckgo/overview)** is a great MCP server that is very easy to use.
4+
5+
Specifically, it provides two tools:
6+
7+
1. **fetch_content** - fetch and parse content from a webpage URL
8+
2. **search** - search DuckDuckGo and return formatted results
9+
10+
With these tools, you could create agents that can perform online searches, do basic research, and more!
11+
12+
13+
## Starting a MCP Gateway to use DuckDuckGo
14+
15+
1. Create a `compose.yaml` file with the following contents:
16+
17+
```yaml save-as=compose.yaml
18+
services:
19+
gateway:
20+
image: docker/mcp-gateway
21+
command:
22+
- --servers=duckduckgo
23+
- --transport=streaming
24+
ports:
25+
- 8811:8811
26+
volumes:
27+
- /var/run/docker.sock:/var/run/docker.sock
28+
```
29+
30+
To explain the flags:
31+
32+
- `--servers=duckduckgo` - configure the MCP Gateway to use the duckduckgo server from the Docker MCP Catalog
33+
- `--transport=streaming` - configure the MCP Gateway to use the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http)
34+
- `/var/run/docker.sock:/var/run/docker.sock` - mount the Docker socket, which is required to actually launch the DuckDuckGo MCP server
35+
36+
37+
2. Start the gateway using Docker Compose:
38+
39+
```bash terminal-id=compose
40+
docker compose up
41+
```
42+
43+
In the log output, you should see output similar to the following:
44+
45+
```plaintext no-copy-button
46+
gateway-1 | - Reading configuration...
47+
gateway-1 | - Reading catalog from [https://desktop.docker.com/mcp/catalog/v2/catalog.yaml]
48+
gateway-1 | - Configuration read in 198.760708ms
49+
gateway-1 | - Those servers are enabled: duckduckgo
50+
gateway-1 | - Listing MCP tools...
51+
...
52+
...
53+
gateway-1 | - Using images:
54+
gateway-1 | - mcp/duckduckgo@sha256:68eb20db6109f5c312a695fc5ec3386ad15d93ffb765a0b4eb1baf4328dec14f
55+
gateway-1 | > Images pulled in 37.201917ms
56+
gateway-1 | - Verifying images [mcp/duckduckgo]
57+
gateway-1 | > Images verified in 887.355875ms
58+
gateway-1 | > Initialized in 1.640829209s
59+
gateway-1 | > Start streaming server on port 8811
60+
```
61+
62+
That's it! The MCP Gateway is up and running!
63+
64+
65+
66+
## Using the MCP Inspector
67+
68+
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a great tool to directly interact with MCP servers, including the MCP Gateway.
69+
70+
1. Start the MCP Inspector by using the following `npx` command:
71+
72+
```bash terminal-id=inspector
73+
npx --yes @modelcontextprotocol/inspector
74+
```
75+
76+
2. Once it finishes, open the MCP Inspector running at :tabLink[http://localhost:6274]{href="http://localhost:6274" title="MCP Inspector"}.
77+
78+
3. Configure the MCP Inspector to connect to a MCP server with the following configuration:
79+
80+
- **Transport Type:** Streamable HTTP (you configured this in the Compose file)
81+
- **URL:** http://localhost:8811
82+
83+
Click **Connect** when you're done!
84+
85+
4. Select the **Tools** tab and then click the **List Tools** button.
86+
87+
You should see both the `fetch_content` and `search` tools appear.
88+
89+
5. Select the **search** tool by clicking on it.
90+
91+
This will open a form to fill out the required parameters.
92+
93+
6. In the _query_ field, type in "Docker MCP Gateway".
94+
95+
7. Click the **Run Tool** button.
96+
97+
After a brief time, you should see your search results!
98+
99+
While running the `search` tool, the Docker MCP Gateway started a DuckDuckGo container, delegated the running of the tool to it, got the results, stopped the container, and sent the results back to the inspector.
100+
101+
102+
103+
## Next steps
104+
105+
While this was a simple MCP server, not all are as straight forward. Many require some sort of authentication or configuration.
106+
107+
In the next step, you'll add the GitHub MCP server to explore this.

‎.labspace/03-adding-a-complex-mcp-server.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Adding a complex MCP server
2+
3+
The **[GitHub MCP server](https://hub.docker.com/mcp/server/github-official/overview)** is a great MCP server that provides the ability to create issues, add comments, list repositories, and more.
4+
5+
In fact, there are (as of the time of writing this) [93 tools](https://hub.docker.com/mcp/server/github-official/tools) provided through this MCP server.
6+
7+
In order to perform operations though, many of them require a Personal Access Token.
8+
9+
To provide this, you will use [Docker Compose secrets](https://docs.docker.com/compose/how-tos/use-secrets/), which the MCP Gateway will safely and securely inject into the MCP server container.
10+
11+
12+
## 🔐 Defining the secret
13+
14+
1. Create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). It is up to you whether you use the classic or fine-grained and how many permissions you grant it.
15+
16+
2. Create a `.env` file with the following contents:
17+
18+
```dotenv save-as=.env
19+
github.personal_access_token=YOUR_TOKEN_HERE
20+
```
21+
22+
Replace `YOUR_TOKEN_HERE` with your Personal Access Token.
23+
24+
2. Update your `compose.yaml` to define the secret:
25+
26+
```yaml
27+
secrets:
28+
github-credential:
29+
file: .env
30+
```
31+
32+
3. Update the `gateway` service in the `compose.yaml` to inject the secret:
33+
34+
```yaml
35+
services:
36+
gateway:
37+
...
38+
secrets:
39+
- github-credential
40+
```
41+
42+
4. Update the `command` for the `gateway` service to tell the MCP Gateway where to find the secrets:
43+
44+
```yaml
45+
services:
46+
gateway:
47+
...
48+
command:
49+
- --servers=duckduckgo
50+
- --transport=streaming
51+
- --servers=github-official
52+
- --secrets=/run/secrets/github-credential
53+
```
54+
55+
5. Run `docker compose up` to apply the changes:
56+
57+
```bash terminal-id=compose2
58+
docker compose up -d
59+
```
60+
61+
62+
63+
## ✅ Validating with the MCP Inspector
64+
65+
With the MCP Gateway now running with the GitHub Official MCP server, you should be able to see a significant increase in the available tools.
66+
67+
1. Open the MCP Inspector at http://localhost:6274.
68+
69+
2. Since the MCP Gateway had to restart, click the **Connect** button to reconnect.
70+
71+
3. Click on the **Tools** tab and then the **List Tools** button to view all of the available tools.
72+
73+
4. Scroll to find the `get_me` tool, which will provide details about the authenticated user.
74+
75+
5. Click the `Run Tool` to execute the tool. You should see output about your user account. If it fails, ensure your Personal Access Token is configured correctly.
76+
77+
78+
79+
## Next steps
80+
81+
You now have two MCP servers configured, but almost 100 tools! Each tool consumes tokens and context when being sent to the LLM. This slows down every request, increases costs, and can even confuse many models.
82+
83+
In the next section, you'll learn how to filter the tools the MCP Gateway exposes.

‎.labspace/04-filtering-available-tools.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Filtering Tools
2+
3+
The configuration you have for your MCP Gateway currently exposes almost 100 tools, which is a lot!
4+
5+
Every tool description includes details on when to use the tool, available parameters, and sometimes examples on how to use it.
6+
7+
These descriptions must be processed on every request, making your AI apps slower, more costly, and potentially less accurate (lots of tools can confuse models).
8+
9+
## Updating the MCP Gateway configuration
10+
11+
Fortunately, the MCP Gateway makes it easy to filter the tools it exposes.
12+
13+
1. Identify the names of the tools you want to expose from each MCP server.
14+
15+
For this lab, you will expose both tools from the DuckDuckGo server and a few tools related to pull requests and issues.
16+
17+
The list will include `fetch_content`, `search`, `get_pull_request`, `get_pull_request_diff`, and `get_pull_request_files`, `get_issue`, and `get_issue_comments`.
18+
19+
2. Update the `compose.yaml` file to include the list of tools with the `--tools` flag:
20+
21+
22+
```yaml
23+
services:
24+
gateway:
25+
command:
26+
...
27+
- --tools=fetch_content,search,get_pull_request,get_pull_request_diff,get_pull_request_files,get_issue,get_issue_comments
28+
```
29+
30+
31+
3. Restart the gateway to apply the tool filtering:
32+
33+
```bash terminal-id=compose2
34+
docker compose up -d
35+
```
36+
37+
38+
39+
## Validating the tool filtering
40+
41+
1. Open the MCP Inspector (http://localhost:6274)
42+
43+
2. Reconnect to the server and list the tools
44+
45+
3. Validate you see only seven tools now.
46+
47+
4. Get the details for a pull request by running the `get_pull_request` tool with the following configuration:
48+
49+
- **Tool:** `get_pull_request`
50+
- **owner:** `docker`
51+
- **pullNumber:** 99
52+
- **repo:** welcome-to-docker

0 commit comments

Comments
 (0)