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.

• Manual URL Override (set_api_url): If auto-discovery can't find the right API, save its spec URL directly. Persisted on a volume until you change or clear it.

• Interactive Fallback: On clients that support MCP elicitation, get_openapi_spec asks the user for the URL directly when discovery fails, and saves the answer automatically—no separate set_api_url call needed.

Related MCP server: Swagger MCP Server

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",
        "-v",
        "proratia-mcp-data:/app/data",
        "proratia-mcp:latest"
      ]
    }
  }
}

Once the server is connected to your client (STDIO or SSE—see the sections below), two tools are exposed: get_openapi_spec and set_api_url. Just ask your agent to fetch the API spec in plain language, e.g.:

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

If auto-discovery can't find it, your client may prompt you for the URL directly (if it supports MCP elicitation)—just answer and it's remembered automatically. Otherwise, tell your agent the URL directly and it'll save it for you:

"The API spec is at http://localhost:4000/swagger.json, use that from now on."

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

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

{
  "tool": "set_api_url",
  "arguments": { "url": "http://localhost:4000/swagger.json" }
}

See Available Tools below for details on how discovery works, how to hint it via .env, and how the saved URL persists.

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",
        "-v", 
        "proratia-mcp-data:/app/data",
        "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 -v proratia-mcp-data:/app/data 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 -v proratia-mcp-data:/app/data proratia-mcp:latest

This opens a local web UI where you can invoke get_openapi_spec (no arguments needed) or set_api_url 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.

Tries, in order:

1. A URL saved via set_api_url (or a previous elicitation answer), if one was set.

2. API_BASE_URL (+ OPENAPI_PATH, API_HOST_HEADER), if set in .env, as a fast-path hint.

3. Full auto-discovery—probing combinations of DISCOVERY_HOSTS, DISCOVERY_PORTS, DISCOVERY_PATHS, and DISCOVERY_HOST_HEADERS (all with sane defaults, overridable in .env) and returning the first response containing an openapi or swagger key.

4. If the client supports MCP elicitation, asking the user for the URL directly and saving their answer for next time (same storage as set_api_url).

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.

2. set_api_url

Manually sets the OpenAPI/Swagger spec URL for get_openapi_spec to use, for when auto-discovery can't find the right API.

• Parameters:

  • url (string, required): The full URL to the spec document, e.g. "http://localhost:4000/openapi.json". Pass an empty string to clear the saved URL and revert to the .env hint / auto-discovery.

The value is written to /app/data inside the container and persists across restarts until changed or cleared again—see Persisting the saved URL below for the volume mount required to make this durable.

Persisting the Saved URL

set_api_url writes to /app/data/url.txt inside the container. Without a mounted volume, this is lost the moment the container is removed (which happens on every call in STDIO mode, since it runs with --rm). To make it durable, mount a named volume at that path:

-v proratia-mcp-data:/app/data

This is already included in the mcpServers config examples and the Inspector command above, and in docker-compose.yml for SSE mode. Docker creates the named volume automatically on first use—no manual setup needed.