MCP Dockerized Server

This repository provides a minimal MCP server based on [fastmcp]. The server exposes the Streamable HTTP transport and protects all requests using a simple API key authentication system.

Use Cases

Local AI Model Serving: Run an MCP server locally to interact with AI models through a standardized interface
Development Environment: Set up a consistent development environment for applications that consume MCP services
Prototyping: Quickly test MCP-based applications without complex cloud setup
Self-hosted AI Solutions: Deploy in environments where cloud-based solutions aren't feasible
Integration Testing: Use as a stable test backend for applications that depend on MCP services

Installation and Setup

Prerequisites

Docker and Docker Compose installed on your system
Basic familiarity with command-line operations
At least 500MB of free disk space

Build and run with Docker

# Pull the latest image
docker pull antpavlenkohmcorp/mcp-dockerized:latest

# Run the container
docker run -p 8000:8000 -v mcp_data:/data antpavlenkohmcorp/mcp-dockerized

The container stores API keys in /data/api_keys.db. Mount a volume to persist keys across restarts.

Run with Docker Compose

Create the included docker-compose.yml file and start the service:

# Start the service
docker compose up --build -d

# View logs
docker compose logs -f

This builds the image if necessary and launches the server on port 8000. The API key database is persisted in the mcp_data volume.

Generate API keys

Use the management CLI inside the container to create keys:

docker run --rm -v mcp_data:/data mcp-server python manage.py generate-key

If you're using Docker Compose:

docker compose run --rm mcp python manage.py generate-key

Generated keys are written to /data/api_keys.db inside the container or the mounted volume. You can confirm the file exists by listing it with a one-off container:

docker run --rm -v mcp_data:/data mcp-server ls -l /data/api_keys.db

The printed key can then be supplied via the X-API-Key header or api_key query parameter when calling the server.

Endpoints

The server exposes two simple HTTP endpoints:

Path	Method	Description
`/mcp`	`POST`	Streamable HTTP transport for MCP requests. Requires a valid API key.
`/generate-key`	`POST`	Generates a new API key. Requires an existing valid API key.

Interactive API documentation is available at /docs (also accessible via /doc) with the raw schema at /openapi.json.

Example requests

Generate a key via HTTP

curl -X POST http://localhost:8000/generate-key \
     -H "X-API-Key: <your-api-key>"

Call the MCP endpoint

You can issue JSON-RPC requests directly. The example below sends a ping request:

curl -X POST http://localhost:8000/mcp \
     -H "Content-Type: application/json" \
     -H "X-API-Key: <your-api-key>" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "ping"}'

Call a tool via HTTP

Tools are invoked using the tools/call method. Provide the tool name and any arguments in the JSON-RPC payload. The example below runs the built-in terminal tool:

curl -X POST http://localhost:8000/mcp \
     -H "Content-Type: application/json" \
     -H "X-API-Key: <your-api-key>" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "terminal", "arguments": {"cmd": "echo hello"}}}'

Using the Python Client

For more advanced interaction you can use the fastmcp Python client:

import asyncio
from fastmcp.client import Client, StreamableHttpTransport

async def main():
    transport = StreamableHttpTransport(
        "http://localhost:8000/mcp",
        headers={"X-API-Key": "<your-api-key>"},
    )
    async with Client(transport) as client:
        tools = await client.list_tools()
        print(tools)
        result = await client.call_tool("terminal", {"cmd": "echo hello"})
        print(result[0].text)

asyncio.run(main())

Plugins

Additional tools and resources can be added by placing modules in the plugins package. Each module should expose a setup(server) function which receives the FastMCP instance and registers tools or resources. All modules in this package are automatically imported on startup.

This repository ships with a terminal plugin providing a simple tool for running commands on the host system.

Creating a Custom Plugin

Create a new Python module in the plugins directory
Implement the setup(server) function
Register your tools or resources

Example plugin structure:

# plugins/my_plugin.py
from fastmcp import Tool, FastMCP

def setup(server: FastMCP):
    @server.tool("my_tool")
    async def my_tool(params: dict):
        # Tool implementation
        return {"result": "Success!"}

Configuration

The server can be configured using the following environment variables:

Variable	Description	Default
`MCP_DB_PATH`	Path to the SQLite database file for API keys	`/data/api_keys.db`
`MCP_PORT`	Port on which the server listens	`8000`

Example usage with custom values:

docker run -p 9000:9000 -v mcp_data:/custom_data -e MCP_PORT=9000 -e MCP_DB_PATH=/custom_data/keys.db mcp-server

Troubleshooting

API Key Issues

Problem: "Invalid API key" errors when making requests Solution: Ensure you're using a valid API key generated with the generate-key command. Keys are stored in the database file at the path specified by MCP_DB_PATH.

Problem: API keys not persisting across container restarts Solution: Make sure you're mounting a volume correctly to store the database file:

docker run -p 8000:8000 -v mcp_data:/data mcp-server

Connection Issues

Problem: Cannot connect to the server Solution: Verify that:

The server is running (docker ps should show the container)
You're connecting to the correct port (default is 8000)
There are no firewall rules blocking the connection

Problem: Connection refused errors Solution: Check if the port is already in use by another service:

lsof -i :8000

Plugin Issues

Problem: Custom plugins aren't being loaded Solution: Ensure your plugin:

Is placed in the plugins directory
Contains a setup(server) function
Has no syntax errors

Problem: Errors when calling tools Solution: Check the server logs for detailed error messages:

docker logs <container_id>

Performance Tuning

For production use, consider adjusting these settings:

Increase container resources (CPU/memory) for heavy workloads
Use a dedicated volume with high I/O performance for the database
Set appropriate timeout values for your specific use case

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A minimal, containerized MCP server that exposes a Streamable HTTP transport with API key authentication, allowing secure access to MCP endpoints.

Related MCP Servers

MCP-OpenAPI
rmasters
-
security
A
license
-
quality
An MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.
Last updated -
2
Python
MIT License
mcp-confluentofficial
confluentinc
A
security
A
license
A
quality
An MCP server implementation built to interact with Confluent Kafka and Confluent Cloud REST APIs.
Last updated -
24
122
78
TypeScript
MIT License
HTTP OAuth MCP Server
NapthaAI
-
security
A
license
-
quality
A reference implementation for creating an MCP server supporting Streamable HTTP & SSE Transports with OAuth authorization, allowing developers to build OAuth-authorized MCP servers with minimal configuration.
Last updated -
5
TypeScript
MIT License
OpenAPI MCP Server
oneWalker
-
security
A
license
-
quality
A server that implements the Model Context Protocol (MCP) with StreamableHTTP transport, enabling standardized interaction with model services through a RESTful API interface.
Last updated -
195
1
JavaScript
MIT License

View all related MCP servers

MCP Dockerized Server