Proratia MCP Server (FastMCP + Docker)

A high-performance, containerized Model Context Protocol (MCP) server built with FastMCP (Python).

This server is a generic, bare-minimum MCP boilerplate for giving agents access to a locally running API's OpenAPI/Swagger spec, completely inside a Docker container. It is not tied to any specific backend—it auto-discovers whatever API is running locally, or repoint it via .env configuration, no code changes required.

No local runtimes (Python, Node, etc.) are required on the host machine—only Docker is required.

---

Features

• OpenAPI Spec Fetcher (get_openapi_spec): Fetches the Swagger/OpenAPI JSON spec from a locally running API. Requires no configuration or arguments—auto-discovers the API by probing common hosts/ports/paths.

---

Directory Structure

proratia-mcp/
├── Dockerfile             # Container configuration with unbuffered I/O
├── docker-compose.yml     # Service compose definition for network (SSE) mode
├── .dockerignore          # Build-context exclusions
├── .env.example           # Template for local environment configuration
├── requirements.txt       # Python dependencies (fastmcp, httpx, python-dotenv)
├── server.py              # Main FastMCP server implementation
└── README.md              # This guide

---

1. Quick Start: Build the Docker Image

Build the docker image locally using the terminal. Open a terminal in the proratia-mcp directory and run:

docker build -t proratia-mcp:latest .

Configure the environment

Copy .env.example to .env:

cp .env.example .env

MCP_PORT=8000

MCP_PORT is the only setting needed to get started—it controls which port the server listens on (and publishes) in SSE mode via docker-compose.

No API configuration is required: get_openapi_spec takes no arguments and auto-discovers a locally running API by probing common hosts/ports/paths. If you want to skip the scan for a faster/more reliable lookup, .env.example has commented-out variables (API_BASE_URL, OPENAPI_PATH, API_HOST_HEADER, and the DISCOVERY_* candidate-list overrides) you can uncomment as needed.

---

2. How to Use the MCP

Add this to your MCP client's mcpServers configuration (see STDIO or SSE below for client-specific instructions and options):

{
  "mcpServers": {
    "proratia-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/absolute/path/to/proratia-mcp/.env",
        "proratia-mcp:latest"
      ]
    }
  }
}

Once the server is connected to your client (STDIO or SSE—see the sections below), the only tool exposed is get_openapi_spec, which takes no arguments. Just ask your agent to fetch the API spec in plain language, e.g.:

"Get the OpenAPI spec for the API running locally."

Example manual invocation (e.g. via MCP Inspector):

{
  "tool": "get_openapi_spec",
  "arguments": {}
}

See Available Tools below for details on how discovery works and how to hint it via .env.

---

3. Integration with LLM Clients (STDIO Mode)

In STDIO mode, the LLM client (e.g., Claude Desktop, Cursor, Cline, Agy, Windsurf, or any other MCP-compatible agent) launches the Docker container as a subprocess and communicates with it using stdin and stdout.

A. Standard mcpServers JSON Configuration

Most MCP clients share the same mcpServers JSON schema, just in a client-specific config file. Add proratia-mcp there, making sure to pass the -i (interactive) flag so stdio streams stay open, and --env-file to load your .env configuration:

{
  "mcpServers": {
    "proratia-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file", "/absolute/path/to/proratia-mcp/.env",
        "proratia-mcp:latest"
      ]
    }
  }
}

Common config file locations:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: .cursor/mcp.json (project-level) or global MCP settings
• Other clients (Agy, Cline, Windsurf, etc.): check that client's MCP documentation for its config file location—the mcpServers block itself is portable across all of them.

After saving, restart your client (or reload its MCP connections) to pick up the new server.

B. GUI-Based Configuration

Some clients offer a settings UI instead of hand-editing JSON (e.g. Cursor):

1. Go to Settings > Features > MCP (or the equivalent in your client).
2. Click + Add New MCP Server.
3. Fill out the fields:
   • Name: proratia-mcp
   • Type: command
   • Command: docker run -i --rm --env-file /absolute/path/to/proratia-mcp/.env proratia-mcp:latest
4. Save and wait for the status indicator to turn green.

---

4. Running as a Network Service (SSE Mode)

If you prefer to run the server as a background service that clients connect to over HTTP (Server-Sent Events), you can use Docker Compose.

1. Start the service:

   docker-compose up -d
   

2. The server will spin up and listen on the port set by MCP_PORT in your .env file (defaults to 8000). You can configure your MCP clients to connect to http://localhost:${MCP_PORT}/sse.

To stop the service:

docker-compose down

---

5. Testing Changes with MCP Inspector

After modifying server.py, rebuild the image (docker build -t proratia-mcp:latest .) and use the official MCP Inspector to interactively call the tool and verify it behaves as expected before wiring it into an LLM client:

npx @modelcontextprotocol/inspector docker run -i --rm --env-file .env proratia-mcp:latest

This opens a local web UI where you can invoke get_openapi_spec (no arguments needed) and inspect the raw response.

---

Available Tools

1. get_openapi_spec

Fetches the Swagger/OpenAPI JSON spec from a locally running API. Takes no parameters.

• If API_BASE_URL is set in .env, it's tried first as a fast-path hint (combined with OPENAPI_PATH and API_HOST_HEADER, if also set).
• Otherwise, it auto-discovers the API by probing combinations of DISCOVERY_HOSTS, DISCOVERY_PORTS, DISCOVERY_PATHS, and DISCOVERY_HOST_HEADERS—all with sane defaults, overridable in .env—and returns the first response containing an openapi or swagger key.
• API_HOST_HEADER / DISCOVERY_HOST_HEADERS override the HTTP Host header independently of the connection address. Needed when the target sits behind a reverse proxy (e.g. Caddy, Nginx) that routes by virtual host.