MCP Remote Suite

A production-ready Model Context Protocol (MCP) suite over Streamable HTTP, demonstrating remote connectivity, a filesystem roots security boundary, and where sampling (server-initiated LLM requests) fits in.

It ships three runnable apps on top of one transport layer:

Component	Role	Default URL
Server (mcp-server)	FastMCP file server: tools, resources, prompts, sandboxed to a workspace root	http://127.0.0.1:8000
GUI client (mcp-gui)	Manual Gradio UI to discover/run tools, read resources, render prompts	http://127.0.0.1:7861
AI host (mcp-host)	Gradio chat where an OpenAI model drives the MCP tools	http://127.0.0.1:7862

Architecture

src/mcp_remote_suite/
├── config.py            # env-driven settings (pydantic-settings)
├── logging_config.py    # shared logging setup
├── _content.py          # unwrap MCP result objects -> text/dicts
├── server/
│   ├── security.py      # WorkspaceGuard — path-traversal protection
│   ├── files.py         # WorkspaceFiles — testable file operations
│   ├── app.py           # FastMCP factory + entry point
│   └── __main__.py      # python -m mcp_remote_suite.server
├── client/
│   └── base.py          # MCPHTTPClient — transport only, no UI/LLM deps
└── apps/
    ├── gui.py           # MCPHTTPClientApp (manual)
    └── host.py          # MCPHTTPHostApp (LLM-driven, multi-round tool loop)
tests/                   # pytest unit tests for the security boundary + files

Layering: apps depend on client and _content; server depends on security + files. Nothing hardcodes ports/URLs/models — all configuration flows from config.py.

Setup

python -m venv .venv
# Windows: .venv\Scripts\activate    |    Unix: source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # optional — adjust ports, model, OpenAI creds

Run

Start the server, then either app (each in its own terminal):

mcp-server          # http://127.0.0.1:8000
mcp-gui             # http://127.0.0.1:7861  (manual)
mcp-host            # http://127.0.0.1:7862  (AI chat; needs OpenAI creds)

Equivalent module form: python -m mcp_remote_suite.server, etc.

Configuration

All settings come from environment variables or .env (see .env.example). Key ones: SERVER_HOST/SERVER_PORT, WORKSPACE_DIR, SERVER_URL, GUI_PORT/HOST_PORT, LOG_LEVEL, and OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL for the AI host.

Security boundary

Every server-side path goes through WorkspaceGuard.resolve(), which resolves the path and rejects anything escaping the workspace root (.., absolute paths, symlink escapes) with AccessDeniedError. This is the "roots" enforcement that makes the server safe to expose remotely.

Tests

pytest