Company API MCP Server Template

A template for creating Model Context Protocol (MCP) servers that integrate with your company's API using FastMCP.

Overview

This template provides a starting point for building MCP servers that can interact with your company's REST API. It includes:

Authentication handling (Bearer token)
Comprehensive error handling and logging
In-memory caching for improved performance
Rate limiting to prevent API abuse
Full CRUD operations (Create, Read, Update, Delete)
Health check and status monitoring
Docker support for easy deployment
Comprehensive test suite
CI/CD pipeline with GitHub Actions
Example tools for common API operations
Environment variable configuration
Proper async/await patterns

Setup

Clone this repository

Install dependencies:

# Production dependencies
pip install -e .

# Or with development dependencies
make install-dev

Set environment variables:

export API_BASE_URL="https://your-api.example.com"
export API_KEY="your-api-key-here"
export CACHE_TTL="300"  # Optional: cache TTL in seconds
export RATE_LIMIT_REQUESTS="100"  # Optional: rate limit

Docker Setup

Alternatively, use Docker:

# Build and run with docker-compose
docker-compose up --build

# Or build and run manually
docker build -t company-api-mcp .
docker run -e API_BASE_URL="https://your-api.example.com" \
           -e API_KEY="your-api-key" \
           company-api-mcp

Configuration

The server can be configured using environment variables:

API_BASE_URL: Base URL of your company's API
API_KEY: API key for authentication
CACHE_TTL: Cache time-to-live in seconds (default: 300)
RATE_LIMIT_REQUESTS: Maximum requests per minute (default: 100)

Usage

Running the server

python server.py

Available Tools

The template includes six example tools:

get_user_info(user_id): Retrieve user information by ID
search_items(query, limit): Search for items with optional limit
create_item(title, description): Create a new item
update_item(item_id, title, description): Update an existing item
delete_item(item_id): Delete an item
get_api_status(): Check API health and status

Customization

To adapt this template for your API:

Update the API_BASE_URL and authentication method in server.py
Modify the existing tools or add new ones based on your API endpoints
Update the response formatting to match your API's data structure
Add any additional error handling specific to your API

Example Tools Implementation

Basic Tool Template

@mcp.tool()
async def your_custom_tool(param: str) -> str:
    """Description of what your tool does.
    
    Args:
        param: Description of the parameter
    """
    data = await make_api_request(f"your-endpoint/{param}")
    
    if not data or "error" in data:
        return "Error message"
    
    # Format and return your data
    return formatted_response

CRUD Operations Examples

# Create
@mcp.tool()
async def create_resource(name: str, data: str) -> str:
    json_data = {"name": name, "data": data}
    result = await make_api_request("resources", method="POST", json_data=json_data)
    return format_response(result)

# Read
@mcp.tool()
async def get_resource(resource_id: str) -> str:
    result = await make_api_request(f"resources/{resource_id}")
    return format_response(result)

# Update
@mcp.tool()
async def update_resource(resource_id: str, name: str = None) -> str:
    json_data = {}
    if name:
        json_data["name"] = name
    result = await make_api_request(f"resources/{resource_id}", method="PUT", json_data=json_data)
    return format_response(result)

# Delete
@mcp.tool()
async def delete_resource(resource_id: str) -> str:
    result = await make_api_request(f"resources/{resource_id}", method="DELETE")
    return format_response(result)

MCP Integration

To use this server with an MCP client, add it to your MCP configuration:

{
  "mcpServers": {
    "company-api": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "API_BASE_URL": "https://your-api.example.com",
        "API_KEY": "your-api-key"
      }
    }
  }
}

Features

Caching

The server includes an in-memory cache to improve performance and reduce API calls. Cache entries expire after the configured TTL (default: 5 minutes).

Rate Limiting

Built-in rate limiting prevents API abuse by limiting the number of requests per minute (default: 100 requests/minute).

Logging

Comprehensive logging for debugging and monitoring:

Request/response logging
Cache hit/miss logging
Error logging with details
Rate limit warnings

Error Handling

Comprehensive error handling for:

HTTP status errors
Network timeouts
JSON parsing errors
API authentication failures
Rate limit exceeded

Flexible HTTP Methods

Support for all common HTTP methods:

GET: Retrieve data (with caching)
POST: Create new resources
PUT: Update existing resources
DELETE: Remove resources

Development

Project Structure

.
├── server.py           # Main MCP server implementation
├── main.py            # Simple CLI entry point
├── pyproject.toml     # Project configuration
├── README.md          # This file
└── .gitignore         # Git ignore rules

Adding New Tools

Define your tool function with the @mcp.tool() decorator
Use make_api_request() to call your API
Handle errors appropriately
Format the response for the user

Testing

Run the test suite:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=. --cov-report=html

# Run specific test file
pytest tests/test_server.py -v

Code Quality

Using ruff for linting and formatting:

# Install development dependencies
make install-dev

# Run all checks
make check

# Fix linting issues automatically
make fix

# Run individual tools
make lint      # Check for issues
make format    # Format code
make test      # Run tests
make test-cov  # Run tests with coverage

Or run commands directly:

# Lint code
ruff check .

# Format code
ruff format .

# Type checking
mypy server.py --ignore-missing-imports

License

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

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.