MoodMNKY MCP Server Stack

> A first-principles guide to running, exposing, and integrating multiple MCP servers in Docker—enabling seamless access via Server-Sent Events (SSE) for OpenAI Agents SDK and other clients.

---

Table of Contents

1. Introduction
2. First Principles of MCP & SSE

1. What Is MCP?
2. Why SSE?
3. Streaming vs. SSE Transport
3. Repository Structure
4. Prerequisites

1. Docker & Docker Compose
2. Cloudflare Tunnel (Cloudflared)
3. Domain & DNS Setup
4. OpenAI Agents SDK
5. Environment Variables

1. .env.example
2. Creating Your .env
3. Filesystem MCP Default Path
6. Getting Started with Docker Compose

1. Cloning the Repository
2. Launching All MCP Servers
3. Verifying Local /tools Endpoints
7. Exposing MCP Servers via Cloudflare Tunnel

1. Why Use a Tunnel?
2. Installing & Authenticating cloudflared
3. Creating a Tunnel & DNS Routes
4. Cloudflared config.yml Example
5. Starting cloudflared as a Service
6. Verifying Public SSE Endpoints
8. Integrating with OpenAI Agents SDK

1. Example Python Code Snippet
2. Configuring MCPServerSse
9. SSE vs. Streamable HTTP: Tradeoffs
10. Troubleshooting & Best Practices

1. Health Checks
2. Port Conflicts
3. Securing Secrets
4. Redis Persistence
5. Updating MCP Versions
11. Extending the MCP Stack
12. License

---

Introduction

The MoodMNKY MCP Server Stack is a standalone repository that orchestrates a diverse array of Model Context Protocol (MCP) servers—all containerized via Docker—behind one convenient docker-compose.yml. This stack enables:

Rapid deployment of numerous tool‐providing MCP servers (e.g., Notion, Sequential Thinking, Brave Search, Tavily, Firecrawl, Fetch, GitHub, Supabase‐Dev, Context7, YouTube Transcript, Memory via Redis, and more).
Unified configuration through a single .env file containing all host‐port bindings, API keys, and paths.
Out‐of‐the‐box integration for OpenAI Agents SDK (via SSE) and other SSE‐capable clients.
Optional exposure of each MCP endpoint over the public internet using Cloudflare Tunnel—preserving firewall safety while providing secure external access.

This README takes a first-principles approach: it explains the “why” behind each step (not just the “how”), so that developers unfamiliar with MCP, SSE, Docker, or Cloudflare Tunnels can still grok exactly what’s happening, why it matters, and how to adapt it to future needs.

---

First Principles of MCP & SSE

What Is MCP?

MCP (Model Context Protocol) is an open‐source specification that allows AI agents (e.g., GPT‐4‐powered assistants) to call out to external “tool” services.
Each MCP server publishes a set of tool signatures (names, arguments, descriptions) over an HTTP endpoint (typically /tools).
When an agent needs to “CALL” a tool, it sends a JSON‐encoded POST to /call, and the MCP server executes the tool (e.g., fetch a web page, query a database, run code) and streams results back.

SSE (Server‐Sent Events) is an HTTP‐based, one‐way streaming protocol where the server can push JSON events to the client over a persistent connection.
In the MCP context, SSE is used for two phases:

Simplicity: SSE is built on plain HTTP, so it works through most proxies, firewalls, and load balancers without special configuration.
Automatic Reconnect: Native reconnection semantics handle transient network blips.
Low Overhead: No WebSocket handshake or protocol framing—just text‐based events.
Unidirectional: Agents still send tool invocations via normal HTTP. SSE is only used to receive streamed results, which aligns well with MCP’s model.

Some MCP servers implement a separate “streamable‐HTTP” transport (chunked transfer encoding) instead of SSE.
SSE (Favored Here):

Standardized event format (data: { ... }).
Built‐in reconnection.
Works across most HTTP/2‐compatible environments.
Streaming/Chunked HTTP:

Simpler for extremely lightweight servers.
No built‐in “event” framing—clients must parse chunks manually.
Recommendation: Unless you have a very specific reason, use SSE. All reference MCP servers in this stack default to SSE, ensuring uniform behavior.

---

Repository Structure

moodmnky-mcp-server-stack/
├── README.md
├── docker-compose.yml    # Orchestrates all MCP services
└── .env.example          # Template for environment variables

README.md: (this file) Explains setup, usage, first‐principles rationale, and tutorials.
docker-compose.yml: Declares 18 services (MCP servers + Redis). Each references environment variables for secrets, host‐port bindings, or paths.
.env.example: Lists all required variables as <PLACEHOLDER> values. Copy to .env, replace placeholders with real values, never commit your actual .env.

Docker Engine (20.10+) and Docker Compose (v2+) installed on your host machine (Linux, macOS, or Windows).
Confirm installation:

  docker --version
  docker-compose --version
  

If you plan to expose MCP servers publicly (e.g., agents hosted remotely), install Cloudflare’s cloudflared on the same host:

1. Download the latest release for your OS from Cloudflare Tunnel documentation.

2. Install (e.g., on Ubuntu):

     curl -LO https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
     sudo dpkg -i cloudflared-linux-amd64.deb
     

3. Verify:

     cloudflared version
     

Domain & DNS Setup

You need a registered domain managed by Cloudflare (e.g., example.com).
For each MCP server you wish to expose publicly, you will create a CNAME record in Cloudflare’s DNS dashboard pointing to the tunnel’s auto‐provisioned hostname (e.g., mcp-tunnel.cfargotunnel.com).

OpenAI Agents SDK

To integrate these MCP servers, you need a Python environment with the OpenAI Agents SDK installed:

  pip install openai-agents
  

Agents will reference MCP endpoints (SSE) in code via MCPServerSse.

---

Environment Variables

.env.example

Below is the complete .env.example file containing placeholder values. Do not commit a file named .env. Instead, copy this to .env and replace every placeholder (<...>) with your actual keys, host ports, and paths.

```ini
###############################################