Skip to main content
Glama

MCP Dockerized Server

by antpavlenko

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:

PathMethodDescription
/mcpPOSTStreamable HTTP transport for MCP requests. Requires a valid API key.
/generate-keyPOSTGenerates 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

  1. Create a new Python module in the plugins directory
  2. Implement the setup(server) function
  3. 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:

VariableDescriptionDefault
MCP_DB_PATHPath to the SQLite database file for API keys/data/api_keys.db
MCP_PORTPort on which the server listens8000

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:

  1. The server is running (docker ps should show the container)
  2. You're connecting to the correct port (default is 8000)
  3. 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:

  1. Is placed in the plugins directory
  2. Contains a setup(server) function
  3. 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
-
security - not tested
F
license - not found
-
quality - not tested

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.

  1. Use Cases
    1. Installation and Setup
      1. Prerequisites
      2. Build and run with Docker
      3. Run with Docker Compose
      4. Generate API keys
    2. Endpoints
      1. Example requests
        1. Generate a key via HTTP
        2. Call the MCP endpoint
        3. Call a tool via HTTP
        4. Using the Python Client
      2. Plugins
        1. Creating a Custom Plugin
      3. Configuration
        1. Troubleshooting
          1. API Key Issues
          2. Connection Issues
          3. Plugin Issues
        2. Performance Tuning

          Related MCP Servers

          • -
            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
          • A
            security
            A
            license
            A
            quality
            An MCP server implementation built to interact with Confluent Kafka and Confluent Cloud REST APIs.
            Last updated -
            24
            52
            77
            TypeScript
            MIT License
            • Apple
          • -
            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
          • -
            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 directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/antpavlenko/mcp_dockerized'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server