MCP Client-Server Deployment

This project deploys an MCP (Model Context Protocol) client-server architecture where:

• The client spawns the server as a subprocess using stdio communication
• The client exposes a REST API for remote interaction
• The server provides tools for accessing strategic planning data

Architecture

┌─────────────────────────────────────────┐
│  Render Web Service                     │
│  ├─ app.py (FastAPI - Client)           │
│  │   ├─ REST API endpoints              │
│  │   ├─ Talks to Groq/LLM               │
│  │   └─ Calls MCP server via stdio      │
│  │                                       │
│  └─ db.py (MCP Server - subprocess)     │
│      └─ Provides MCP tools:             │
│         - get_institute_about           │
│         - list_strategic_plans          │
│         - get_strategic_map             │
└─────────────────────────────────────────┘

Local Development

Prerequisites

• Python 3.13
• uv package manager

Setup

1. Install dependencies:

# Using uv (recommended)
cd db_chat && uv sync
cd ../mcp-client && uv sync

# Or using pip
pip install -r requirements.txt

2. Create .env file in the root with:

# Groq API Configuration
GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile

# API Configuration
GENERAL_BASE_URL=your_general_base_url_here
STRATEGIC_BASE_URL=your_strategic_base_url_here
API_USERNAME=your_username_here
API_PASSWORD=your_password_here

# Optional
MAX_TURNS=10

Run Locally

Option 1: Interactive Client (Terminal)

cd mcp-client
uv run python client.py ../db_chat/db.py

Option 2: Web API (REST)

python app.py

Then access at http://localhost:8000

API Endpoints

Health Check

GET /
GET /health

List Available Tools

GET /tools

Response:

{
  "tools": [
    {
      "name": "get_institute_about",
      "description": "Return the Arabic 'about institute' text",
      "input_schema": {}
    },
    ...
  ]
}

Query the System

POST /query
Content-Type: application/json

{
  "query": "What is the institute about?"
}

Response:

{
  "response": "The institute is...",
  "error": null
}

Deployment to Render

Using render.yaml (Recommended)

1. Push code to GitHub
2. Connect your GitHub repo to Render
3. Render will auto-detect render.yaml
4. Set environment variables in Render dashboard:
   • GROQ_API_KEY
   • GENERAL_BASE_URL
   • STRATEGIC_BASE_URL
   • API_USERNAME
   • API_PASSWORD
5. Deploy!

Manual Deployment

1. Create a new Web Service on Render
2. Connect your repository
3. Configure:
   • Environment: Python
   • Build Command: pip install -r requirements.txt
   • Start Command: python app.py
   • Python Version: 3.13.0
4. Add environment variables (see above)
5. Deploy

Testing the Deployed API

Using curl

# Health check
curl https://your-app.onrender.com/health

# List tools
curl https://your-app.onrender.com/tools

# Query
curl -X POST https://your-app.onrender.com/query \
  -H "Content-Type: application/json" \
  -d '{"query": "List the latest 5 strategic plans"}'

Using Python

import requests

url = "https://your-app.onrender.com/query"
response = requests.post(url, json={"query": "What is the institute about?"})
print(response.json()["response"])

Project Structure

.
├── app.py                          # FastAPI web service (entry point)
├── requirements.txt                # Python dependencies
├── render.yaml                     # Render deployment config
├── runtime.txt                     # Python version
├── db_chat/                        # MCP Server
│   ├── db.py                       # MCP server implementation
│   ├── external_api_service.py     # API client
│   └── pyproject.toml              # Server dependencies
├── mcp-client/                     # MCP Client
│   ├── client.py                   # MCP client implementation
│   ├── llm_service.py              # LLM integration
│   └── pyproject.toml              # Client dependencies
└── README.md                       # This file

Environment Variables

Variable	Description	Required
GROQ_API_KEY	Groq API key for LLM	Yes
GROQ_MODEL	Groq model name	No (default: llama-3.3-70b-versatile)
GENERAL_BASE_URL	General API base URL	Yes
STRATEGIC_BASE_URL	Strategic API base URL	Yes
API_USERNAME	API username	Yes
API_PASSWORD	API password	Yes
MAX_TURNS	Max conversation turns	No (default: 10)
PORT	Server port	No (default: 8000)

How It Works

1. Startup: When app.py starts, it:

   • Creates an MCPClient instance
   • Spawns db.py as a subprocess
   • Establishes stdio communication between them

2. Query Processing: When you send a query:

   • FastAPI receives the HTTP request
   • Passes it to the MCP client
   • Client sends it to Groq LLM
   • LLM decides if it needs tools
   • If yes, calls the MCP server via stdio
   • Server fetches data from external APIs
   • Response flows back: Server → Client → LLM → API response

3. Shutdown: When the service stops:

   • MCP client gracefully closes the connection
   • Server subprocess terminates
   • Resources are cleaned up

Troubleshooting

"MCP client not initialized"

• Check that all environment variables are set
• Review Render logs for startup errors

"No module named 'mcp'"

• Ensure requirements.txt includes all dependencies
• Rebuild the service on Render

LLM not calling tools

• Verify GROQ_API_KEY is valid
• Check that the query actually requires tool usage

License

MIT