Skip to main content
Glama
mcp-production-mastery

mcp-production-mastery

by MnMansour

Production MCP Agent Architecture

A production-grade, end-to-end implementation of an AI Agent connecting to external tools using the Model Context Protocol (MCP), enforcing Deterministic Structured Outputs with Zod, and instrumented with Langfuse Observability.


πŸ—οΈ Architecture Overview

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”          Stdio Transport          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                β”‚ ◄── 1. tools/list Discovery ───► β”‚                   β”‚
β”‚   MCP Client   β”‚                                  β”‚    MCP Server     β”‚
β”‚  (Agent Loop)  β”‚ ◄── 2. tools/call Execution ───► β”‚  (FastMCP Engine) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜                                  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
        β”‚                                                     β”‚
        β”‚ 3. LLM Invocations & Structured Outputs             β”‚ Audit Logs
        β–Ό                                                     β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                                  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   OpenAI API   β”‚                                  β”‚   Target Storage  β”‚
β”‚    (gpt-4o)    β”‚                                  β”‚   / Infrastructureβ”‚
β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜                                  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
        β”‚
        β”‚ 4. Telemetry Spans, Latency & Cost Tracing
        β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚    Langfuse    β”‚
β”‚  Observability β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Related MCP server: fde-assessment

⚑ Key Features

  • Model Context Protocol (MCP): Implements standard Client-Server decoupled tool discovery and execution over stdio transport using standard JSON-RPC 2.0.

  • 100% Deterministic JSON Schemas: Uses OpenAI's zodResponseFormat and zodFunction helpers to eliminate non-deterministic markdown or missing fields at runtime.

  • Full Observability & Tracing: Instrument traces, model generations, and tool execution spans via Langfuse for latency monitoring and token cost tracking.

  • Modular TypeScript Design: Built with Modern ES Modules, strict typing, clean separation of concerns, and native execution via tsx.

  • Container Ready: Includes Docker & Docker Compose setup for production deployment.


πŸ“‚ Project Structure

mcp-production-mastery/
β”œβ”€β”€ .env.example
β”œβ”€β”€ Dockerfile
β”œβ”€β”€ docker-compose.yml
β”œβ”€β”€ package.json
β”œβ”€β”€ tsconfig.json
└── src/
    β”œβ”€β”€ client.ts             # Main MCP Client agent loop & execution engine
    β”œβ”€β”€ server.ts             # MCP Server exposing standard operational tools
    β”œβ”€β”€ config/
    β”‚   └── telemetry.ts      # Centralized Langfuse SDK initialization
    β”œβ”€β”€ schemas/
    β”‚   └── output.schemas.ts # Zod contracts for agent responses
    └── tools/
        β”œβ”€β”€ database.tool.ts  # Database mutation tool implementation
        └── ping.tool.ts      # System infrastructure diagnostic tool

πŸš€ Getting Started

Prerequisites

  • Node.js v18+

  • npm v9+

  • OpenAI API Key

  • Langfuse Account Key Pair (Cloud or Self-Hosted)

Step 1: Clone & Install Dependencies

git clone [https://github.com/YOUR_USERNAME/mcp-production-mastery.git](https://github.com/YOUR_USERNAME/mcp-production-mastery.git)
cd mcp-production-mastery
npm install

Step 2: Configure Environment Variables

Copy .env.example to .env and fill in your API credentials:

cp .env.example .env

Step 3: Run the Agent

Execute the full client-server loop in development mode:

# Run the complete agent orchestration loop
npm run start:client

To run the standalone MCP server process listening on Stdio:

npm run start:server

🐳 Docker Deployment

To build and run the MCP Server container using Docker Compose:

# Build and run server image
docker-compose up --build

πŸ› οΈ Modifying & Extending Tools

To add a new operational tool to the MCP Server:

  1. Create a new Zod input schema and execution function under src/tools/.

  2. Register the tool inside src/server.ts using server.tool(...).

  3. The MCP Client will automatically discover the new tool on launch via tools/list without requiring client modifications.


πŸ“ License

Distributed under the MIT License. See LICENSE for details.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Exposes a verified tool registry (calculator, sandboxed file read, web fetch) over MCP stdio, enabling any MCP-capable client to reuse the same tools from the inspectable ReAct loop.
      3
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP tool calls with strict schema validation and stdio isolation, while providing a security gateway for tool-level authorization, streaming PII redaction, and model failover routing.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides an MCP stdio interface for AI agents to propose tool calls that are validated against task policy, held for human approval when required, executed in a sandboxed Linux environment, and recorded in an audit log.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables any MCP client to drive a retrieval-grounded multi-agent workflow over stdio JSON-RPC, with journalled effects so recorded runs replay byte-for-byte from their trace. It also lets an agent answer retrieval by calling a tool on another MCP server.
      MIT