MCP HTTP Advanced Host-Client-Server Application

A production-ready implementation of the Model Context Protocol (MCP) over HTTP with LLM tool integration, featuring OpenAI GPT models, comprehensive security, resilience patterns, and enterprise testing.

🎯 Key Features

Core Capabilities

• ✅ HTTP-based MCP - Distributed tool protocol over HTTP

• ✅ LLM Integration - OpenAI GPT model with function calling

• ✅ Filesystem Tools - Read/write files with security

• ✅ Web UI - Gradio interface for exploration and testing

• ✅ AI Agent - Autonomous tool execution based on user intent

Production Ready

• ✅ Configuration Management - JSON config with env var substitution

• ✅ Security - Path traversal prevention, input validation, UTF-8 enforcement

• ✅ Resilience - Connection retry, heartbeat verification, error recovery

• ✅ Logging - Structured logging with configurable levels

• ✅ Testing - 75+ tests with 90%+ coverage, CI/CD pipeline

• ✅ Documentation - Comprehensive guides for configuration and testing

Related MCP server: filesystem-mcp

📦 What's Included

🎯 mcp_http_server.py          HTTP MCP Server (FastMCP)
🎨 mcp_http_client_app.py      Web UI (Gradio) for exploration
🤖 mcp_http_host_app.py        AI Agent with OpenAI integration
📋 mcp_config.py               Configuration management with priority resolution
⚙️  mcp_config.json            Production configuration
🧪 tests/                      75+ test cases with pytest
🔄 .github/workflows/ci_cd.yml  GitHub Actions CI/CD pipeline
📚 Documentation               Guides for quick start, config, testing, and review

🚀 Quick Start (5 minutes)

Prerequisites

python 3.9+          # For async/await and type hints
pip package manager  # For dependency installation
OpenAI API key       # For GPT model access

Installation

1. Clone and setup

   git clone <repo>
   cd advanced-mcp-host-client-server-app
   pip install -r requirements.txt

2. Set API key

   export OPENAI_API_KEY=sk-your-key-here

3. Start server

   python mcp_http_server.py
   # Server running on http://127.0.0.1:8000

4. Start AI Host (new terminal)

   python mcp_http_host_app.py http://127.0.0.1:8000 ./workspace
   # Access at http://127.0.0.1:7862

5. Chat with AI

   • Go to http://127.0.0.1:7862

   • Type: "List the files in workspace"

   • AI calls list_files tool automatically!

See QUICKSTART.md for detailed setup instructions.

📖 Documentation

🏗️ Architecture

Component Diagram

┌──────────────────────────────────────────────────────┐
│              MCP Application Suite                    │
└──────────────────────────────────────────────────────┘

    GUI Client                AI Host App            API Clients
   (Gradio UI)         (GPT + Tool Calling)       (Custom clients)
        │                     │                        │
        └─────────────────────┼────────────────────────┘
                              │
                         HTTP/Streamable
                              │
                    ┌─────────▼──────────┐
                    │  HTTP MCP Server   │
                    │   (FastMCP)        │
                    │                    │
                    │ • File Tools       │
                    │ • Resources        │
                    │ • Prompts          │
                    │ • Analysis         │
                    └────────────────────┘
                              │
                         Workspace
                    (./workspace files)

Component Responsibilities

• mcp_http_server.py: Exposes filesystem and analysis tools via HTTP MCP

• mcp_http_client_app.py: Web UI for exploring tools, resources, and prompts

• mcp_http_host_app.py: LLM agent that calls tools autonomously

• mcp_config.py: Centralized configuration with priority resolution

• tests/: Comprehensive test suite for reliability

🔒 Security Features

⚙️ Configuration

Three Tiers (Priority)

1. Command-line arguments  (Highest priority)
   └─ python app.py --model gpt-4o

2. Configuration file
   └─ mcp_config.json with "model": "gpt-4o-mini"

3. Environment variables
   └─ export OPENAI_MODEL=gpt-4o-mini

4. Hardcoded defaults      (Lowest priority)
   └─ DEFAULT_MODEL = "gpt-4o-mini"

Example mcp_config.json

{
  "openai": {
    "api_key": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 8000
  },
  "gui": {
    "host": "127.0.0.1",
    "port": 7862
  },
  "logging": {
    "level": "INFO"
  }
}

See CONFIG.md for complete configuration guide.

🧪 Testing

Run All Tests

pip install -r requirements-test.txt
pytest tests/ -v

Test Coverage

• Overall: 90%+

• Config module: 95%+

• Server module: 90%+

• Client module: 85%+

Test Types

• Unit Tests (60%): Fast, isolated component tests

• Security Tests (20%): Vulnerability and attack prevention

• Integration Tests (20%): Real-world scenarios

See TESTING.md for comprehensive testing guide.

🔄 Resilience Features

📊 Performance

🚀 Deployment

Local Development

# Terminal 1: Server
python mcp_http_server.py

# Terminal 2: GUI Client
python mcp_http_client_app.py http://localhost:8000 ./workspace

# Terminal 3: AI Host
python mcp_http_host_app.py http://localhost:8000 ./workspace

Docker

docker build -t mcp-app .
docker run -e OPENAI_API_KEY=$OPENAI_API_KEY -p 8000:8000 -p 7862:7862 mcp-app

GitHub Actions CI/CD

• ✅ Automated testing on Python 3.9-3.11

• ✅ Runs on Linux, macOS, Windows

• ✅ Code quality checks (pylint, black, flake8, mypy)

• ✅ Security checks (bandit, safety)

• ✅ Coverage reporting

See PROJECT_REVIEW.md for deployment details.

🛠️ Tools & Technologies

Core

• FastMCP 2.12.5: MCP server framework

• OpenAI SDK 2.6.1: GPT model integration

• Gradio 5.49.1: Web UI framework

• Uvicorn 0.38.0: ASGI server

• HTTPx: HTTP client

Testing

• Pytest 7.4.3: Test framework

• Pytest-asyncio: Async test support

• Pytest-cov: Coverage reporting

• Black, Pylint, Flake8, MyPy: Code quality

📝 API Reference

Server Tools

read_file(filepath: str) -> str
  # Read file from workspace

write_file(filepath: str, content: str) -> str
  # Write file to workspace

list_files(directory: str) -> List[str]
  # List directory contents

analyze_code(code: str, focus: str = "") -> str
  # Analyze code with LLM

Client Methods

await client.connect()
await client.list_tools()
await client.call_tool(name, arguments)
await client.list_resources()
await client.read_resource(uri)
await client.list_prompts()
await client.get_prompt(name, arguments)

🔐 Security Considerations

✅ Implemented

• Path traversal prevention

• Input validation on all parameters

• UTF-8 encoding enforcement

• Error message safety

• Dependency security checks (CI/CD)

⚠️ To Implement

• API authentication

• Authorization/RBAC

• Rate limiting

• Request signing

• Data encryption at rest

See PROJECT_REVIEW.md for security details.

🤝 Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit changes (git commit -m 'Add amazing feature')

4. Push to branch (git push origin feature/amazing-feature)

5. Open a Pull Request

All PRs must:

• ✅ Pass all tests

• ✅ Maintain 90%+ coverage

• ✅ Pass code quality checks

• ✅ Include documentation

📋 Project Status

✅ Completed

• HTTP MCP server with filesystem tools

• Gradio web UI for tool exploration

• OpenAI integration with function calling

• Configuration management system

• 75+ test cases with CI/CD pipeline

• Comprehensive documentation

• Security hardening

• Resilience patterns

🚧 In Progress

• Enhanced monitoring and metrics

• Performance optimization

• Extended logging

📋 Planned

• Multi-instance load balancing

• Persistent conversation storage

• Database-backed file storage

• Authentication/authorization

• WebSocket support

• Batch operations

• Custom tool templates

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

👥 Author

Deepak Upadhyay - Engineering

🙏 Acknowledgments

• FastMCP team for MCP server framework

• OpenAI for GPT model APIs

• Gradio for web UI components

• Python async/await ecosystem

📞 Support

For issues, questions, or feature requests:

1. Check Documentation

   • QUICKSTART.md - Common tasks

   • CONFIG.md - Configuration help

   • TESTING.md - Test documentation

2. Review Examples

   • Check tests/ for usage examples

   • Review mcp_config.json for setup

3. Debug Issues

   • Enable debug logging: LOG_LEVEL=DEBUG

   • Check PROJECT_REVIEW.md for architecture

   • Run tests: pytest -v to verify setup

🎓 Learning Resources

• Model Context Protocol Spec

• OpenAI Function Calling

• FastMCP Documentation

• Gradio Documentation

Version: 1.0.0
Last Updated: 2024
Status: Production Ready ✅

Made with ❤️ for the agentic engineering community.