Generic MCP Server
A generic, metadata-driven Model Context Protocol (MCP) server implementation that automatically discovers tools from Firestore and dynamically routes tool calls to their respective endpoints.
Overview
This MCP server provides a flexible, scalable architecture for managing tools without requiring code changes. Tools are registered in Google Cloud Firestore, and the server automatically:
- Discovers tools from the Firestore registry at startup
- Dynamically routes tool calls to their configured endpoints
- Supports streaming and synchronous responses
- Manages sessions for MCP protocol compliance
Features
- 🔄 Automatic Tool Discovery: Tools are loaded from Firestore on startup
- 🎯 Dynamic Routing: Tool calls are routed to endpoints defined in metadata
- 📡 Streaming Support: Supports both streaming and synchronous tool execution
- 🔐 Session Management: Maintains MCP session state for client interactions
- 🐳 Docker Ready: Includes Dockerfile for containerized deployment
- ☁️ Cloud Native: Built for Google Cloud Platform with Firestore integration
Architecture```
┌─────────────┐
│ Client │
└──────┬──────┘
│ MCP Protocol (JSON-RPC)
▼
┌─────────────────────┐
│ MCP Server │
│ (FastAPI) │
└──────┬──────────────┘
│
├──► Firestore (Tool Registry)
│ └──► Tool Metadata
│
└──► Dynamic Routing
└──► External Services (run_url)
### How It Works
1. **Tool Registration**: Tools are registered in Firestore's `tool_registry` collection with their metadata
2. **Discovery**: On startup, the server loads all tools from Firestore
3. **Capability Building**: Server builds MCP capabilities based on discovered tools
4. **Dynamic Routing**: When a tool is called, the server routes the request to the `run_url` specified in the tool's metadata
## Prerequisites
- Python 3.11+
- Google Cloud Project with Firestore enabled
- Google Cloud credentials configured (via `gcloud auth application-default login` or service account)
## Installation
### Using pip```bash
pip install -r requirements.txt
Using pipenv```bash
pipenv install
## Configuration
### Firestore Setup
1. Create a Firestore database in your Google Cloud project
2. Create a collection named `tool_registry`
3. Add tool documents with the following structure:```json
{
"name": "tool_name",
"description": "Tool description",
"parameters": {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "Parameter description"
}
},
"required": ["param1"]
},
"output_schema": {
"type": "object",
"properties": {
"result": {"type": "string"}
}
},
"run_url": "https://your-service.com/endpoint",
"metadata": {
"service": "service-name"
}
}
Seeding Firestore
Use the provided seed script to populate Firestore with tool definitions:```bash
python firestore/seed.py
Make sure to update the project ID in `firestore/seed.py` to match your Google Cloud project.
## Running the Server
### Local Development```bash
uvicorn main:app --reload --port 8080
Production (with Gunicorn)```bash
gunicorn main:app -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8080 --workers 2
### Docker```bash
# Build the image
docker build -t mcp-server .
# Run the container
docker run -p 8080:8080 \
-v /path/to/gcloud/credentials.json:/app/credentials.json \
-e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials.json \
mcp-server
API Endpoints
MCP Handler
POST
/mcp
Main MCP protocol endpoint that handles JSON-RPC requests.
Supported Methods
initialize: Initialize a new MCP sessiontools/list: List all available toolstools/call: Execute a tool with optional streaming
Example Request```json
{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/call",
"params": {
"name": "get_pet",
"arguments": {
"pet_id": "123"
},
"stream": false
}
}
#### Example Response```json
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"content": [
{
"type": "text",
"text": "{\"id\": \"123\", \"name\": \"Fluffy\"}"
}
]
}
}
Tool Metadata Schema
Each tool in Firestore must have the following structure:
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Unique tool identifier |
description |
string | Yes | Human-readable tool description |
parameters |
object | Yes | JSON Schema for input parameters |
output_schema |
object | No | JSON Schema for output structure |
run_url |
string | Yes | HTTP endpoint to route tool calls to |
metadata |
object | No | Additional metadata (e.g., service name) |
Project Structure```
petstore_mcp_server/
├── main.py # FastAPI application entry point
├── mcp/
│ ├── registry.py # Firestore tool registry loader
│ └── router.py # MCP protocol router
├── transport/
│ └── sse_transport.py # SSE transport implementation
├── firestore/
│ └── seed.py # Firestore seeding script
├── requirements.txt # Python dependencies
├── Dockerfile # Docker configuration
└── README.md # This file
## Development
### Adding a New Tool
1. Add tool metadata to Firestore's `tool_registry` collection
2. Ensure the `run_url` points to a valid endpoint
3. Restart the server to load the new tool
No code changes required! The server will automatically discover and expose the new tool.
### Testing```bash
# Test tool listing
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/list"
}'
# Test tool execution
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: <session-id>" \
-d '{
"jsonrpc": "2.0",
"id": "2",
"method": "tools/call",
"params": {
"name": "get_pet",
"arguments": {"pet_id": "123"}
}
}'
MCP Protocol Compliance
This server implements the Model Context Protocol specification:
- Protocol Version:
2025-03-26 - Transport: HTTP POST with JSON-RPC 2.0
- Session Management: Via
Mcp-Session-Idheader - Streaming: Supported via Server-Sent Events (SSE)
Dependencies
fastapi: Web frameworkuvicorn: ASGI servergunicorn: Production WSGI serverhttpx: HTTP client for routing tool callsgoogle-cloud-firestore: Firestore client library
License
[Add your license here]
Contributing
[Add contribution guidelines here]
Support
[Add support information here]
