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:

1. Update pyproject.toml with your service name
2. Configure AWS credentials in GitHub secrets
3. 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:

1. Deploy your MCP server
2. Register it in the agent's MCP configuration
3. 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:

1. Edit pyproject.toml:

[tool.poetry.group.dev.dependencies]
oxsci-oma-mcp = { path = "../oxsci-oma-mcp", develop = true }

2. 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

• oxsci-oma-mcp: MCP protocol package
• oxsci-oma-core: OMA framework
• oxsci-shared-core: Shared utilities

License

Proprietary - OxSci.AI