MCP OpenAPI Template MCP Server

How to use

Start by running the server locally to experiment with your OpenAPI-backed MCP. You can run in stdio mode for a local workflow or in SSE mode for remote operation. Once running, you authenticate through the Auth Gateway, fetch credentials for API access, and begin calling tools generated from your OpenAPI specification. Each tool corresponds to an API operation or grouped set of operations, and you can extend the server with custom helper tools for easier usage.

How to install

# Prerequisites
- Python 3.8+ installed on your system
- Access to a shell/terminal
- Optional: Docker for containerized deployment

# 1. Clone or download the template
# Use this approach to start quickly
# git clone https://github.com/jesusperezdeveloper/mcp_openapi_template my-api-mcp
# cd my-api-mcp

# 2. Install dependencies if applicable (typical Python setup)
# Ensure your environment has vendor dependencies ready if the project provides them

# 3. Initialize your service
python -m scripts.init_service \
  --name "github" \
  --display-name "GitHub" \
  --base-url "https://api.github.com" \
  --openapi-url "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"

# 4. Configure authentication gateway in environment (see env vars below)

# 5. Fetch the OpenAPI spec (if applicable)
python -m scripts.fetch_openapi

# 6. Run the server locally (stdio)
PYTHONPATH=vendor python -m src.server

# 7. Or run in remote mode (SSE)
MCP_TRANSPORT=sse PYTHONPATH=vendor python -m src.server

Configuration and security

Configure the runtime and security settings to control access and behavior. The server relies on an Auth Gateway to fetch credentials, and you can tailor validation and policies to your risk tolerance. The main configuration options include the API base URL, the location of the OpenAPI spec, how tools are named, and patterns to block certain operations. You also set how transports are used and how the server authenticates user requests.

Environment variables you should provide to enable authentication and transport behavior include the following. Place these in your environment file or when launching the server.

AUTH_GATEWAY_URL=https://your-auth-gateway.com
AUTH_GATEWAY_API_KEY=your-api-key
API_BASE_URL=https://api.example.com             # optional override
MCP_TRANSPORT=stdio                              # or sse for remote transport
MCP_PORT=8000                                      # optional for SSE mode

Examples and extending with helpers

You can add custom helper tools to simplify common tasks or wrap API interactions in user-friendly functions. The following shows how a custom tool can be registered in your MCP. It uses a decorator to declare a tool and ensures authentication is enforced.

# In src/helpers.py
def register_helper_tools(mcp, auth_params, client_factory, require_auth):
    @mcp.tool(description="My custom tool")
    async def my_tool(param: str) -> dict:
        require_auth()
        # Implementation
        pass

Docker deployment

You can containerize the MCP server for production deployment. Build the image with the OpenAPI spec and run a container exposing the appropriate port.

docker build \
  --build-arg OPENAPI_SPEC_URL="https://api.example.com/openapi.json" \
  -t my-mcp .

# Run
docker run -p 8000:8000 --env-file .env my-mcp

Notes and troubleshooting

If you encounter authentication issues, verify that the Auth Gateway URL and API key are correct and that your user has the necessary permissions to access the API credentials. Ensure the OpenAPI spec URL is reachable and that the server has network access to fetch or validate the spec. For transport-related problems, confirm whether you are running in stdio or SSE mode and adjust MCP_TRANSPORT accordingly.

my_tool

A custom tool registered to the MCP that performs a specific task with authentication enforced.