MCP Server Template
A scaffold project for building MCP (Model Context Protocol) servers using oxsci-oma-mcp.
Features
FastAPI-based MCP server
Built-in tool router with automatic discovery
Example tool implementation
Docker support
CI/CD workflow for deployment (template ready)
Quick Start
1. Setup
# Clone this repository
git clone https://github.com/your-org/your-mcp-server.git
cd your-mcp-server
# Configure CodeArtifact access
./entrypoint-dev.sh
# Install dependencies
poetry install
2. Run Locally
# Start the server
poetry run python -m app.core.main
# Or with uvicorn directly
poetry run uvicorn app.core.main:app --host 0.0.0.0 --port 8060 --reload
The server will start at http://localhost:8060
3. Test the API
Check server status:
curl http://localhost:8060/
Discover available tools:
curl http://localhost:8060/tools/discover
Execute a tool:
curl -X POST http://localhost:8060/tools/example_tool \
-H "Content-Type: application/json" \
-d '{
"arguments": {
"input_text": "Hello World",
"uppercase": true
},
"context": {
"user_id": "user123"
}
}'
Project Structure
.
├── app/
│ ├── core/
│ │ ├── __init__.py
│ │ ├── config.py # Configuration
│ │ └── main.py # FastAPI application
│ └── tools/
│ ├── __init__.py # Import tools here
│ └── example_tool.py # Example tool implementation
├── tests/ # Test files
├── .github/
│ └── workflows/
│ └── docker-builder.yml # CI/CD workflow (template)
├── Dockerfile # Docker configuration
├── pyproject.toml # Poetry dependencies
├── entrypoint-dev.sh # CodeArtifact setup script
└── README.md
Creating New Tools
1. Create a new tool file in app/tools/
# app/tools/my_tool.py
from fastapi import Depends
from pydantic import BaseModel, Field
from oxsci_oma_mcp import oma_tool, require_context, IMCPToolContext
class MyToolRequest(BaseModel):
param1: str = Field(..., description="Parameter description")
class MyToolResponse(BaseModel):
result: str = Field(..., description="Result description")
@oma_tool(
description="My custom tool",
version="1.0.0",
)
async def my_tool(
request: MyToolRequest,
context: IMCPToolContext = Depends(require_context),
) -> MyToolResponse:
# Your tool implementation
result = f"Processed: {request.param1}"
return MyToolResponse(result=result)
2. Import in app/tools/__init__.py
from . import my_tool # noqa: F401
3. Restart the server
The tool will be automatically discovered and available at /tools/my_tool
Configuration
Edit app/core/config.py to customize:
Service name
Environment variables
External service URLs
For production deployments, use environment variables or AWS SSM parameters.
Testing
# Run all tests
poetry run pytest
# Run with coverage
poetry run pytest --cov=app --cov-report=html
# Run specific test types
poetry run pytest -m unit
poetry run pytest -m integration
Docker
Build
docker build -t my-mcp-server:latest .
Run
docker run -p 8060:8060 \
-e ENV=production \
-e SERVICE_NAME=my-mcp-server \
my-mcp-server:latest
Deployment
The project includes a GitHub Actions workflow template for automated deployment:
Update pyproject.toml with your service name
Configure AWS credentials in GitHub secrets
Push to main branch or create a tag to trigger deployment
# Deploy using gh cli
gh workflow run docker-builder.yml \
--field deploy_to_test=true \
--field pump_version=patch
Integration with OMA Core
If you're building tools for an OMA agent service:
Deploy your MCP server
Register it in the agent's MCP configuration
Tools will be automatically discovered and available to agents
Example MCP configuration:
mcp_servers:
my_mcp_server:
enabled: true
base_url: "https://my-mcp-server.example.com"
description: "Custom tools for my agent"
Development Tips
Local Development with oxsci-oma-mcp
To develop against a local version of oxsci-oma-mcp:
Edit pyproject.toml:
[tool.poetry.group.dev.dependencies]
oxsci-oma-mcp = { path = "../oxsci-oma-mcp", develop = true }
Run:
poetry lock
poetry install --with dev
External Service Integration
Use oxsci-shared-core for calling other services:
poetry add oxsci-shared-core --source oxsci-ca
from oxsci_shared_core.auth import ServiceClient
service_client = ServiceClient("my-mcp-server")
data = await service_client.call_service(
target_service_url="https://data-service.example.com",
method="GET",
endpoint="/data/items"
)
Related Projects
License
Proprietary - OxSci.AI