A lightweight, open-source MCP server that can be run locally (via Docker or binary) to connect AI agents to data sources such as BitGo crypto APIs, databases, or file systems, without relying on proprietary cloud services. Includes basic auth, TLS, and MCP message handling.

Quick Start • Features • Examples • Contributing

What is this?

A self‑hosted MCP server that lets developers run AI agent workflows locally without depending on cloud services. It provides TLS‑encrypted endpoints, basic auth, and ready‑to‑use connectors for BitGo, databases, and the file system.
Example usage:

$ ./mcp_server --port 8000
[INFO] MCP server listening on https://0.0.0.0:8000

Problem

Solo developers and small teams struggle to prototype agentic applications because setting up an MCP server requires deep knowledge of the protocol, dealing with complex TLS configuration, or pulling heavyweight enterprise distributions. This slows down iteration and increases operational overhead.

Features

Feature	Description
Local Run (Docker/Binary)	Execute as a Docker container or standalone binary with zero‑cloud‑dependency deployment.
MCP Protocol Support	Implements sampling, logging, and toolInvocation message types as defined by the Model Context Protocol.
TLS Encryption	Enforces TLS 1.2+ for all connections; uses PEM‑encoded certificates and keys.
Basic Auth Middleware	Protects endpoints with a simple Bearer token verification mechanism.
Data Connectors	Includes built‑in connectors for BitGo APIs, relational databases, and local file systems.
Health Check Endpoint	Provides a /health endpoint that returns server status and timestamp.
Configurable Port	Server port can be set via the MCP_PORT environment variable (default 8000).
Extensible Handler	Modular mcp/handler.py makes it easy to add new message types or data sources.

Quick Start

1. Clone the repository:

   git clone https://github.com/yourorg/selfhosted-mcp-server.git
   cd selfhosted-mcp-server
   

2. Install dependencies (requires Python 3.11+):

   pip install -e .
   

3. Run the server using the binary:

   ./mcp_server --port 8000
   

   Or run via Docker:

   docker build -t selfhosted-mcp .
   docker run -p 8000:8000 selfhosted-mcp
   

Examples

Health Check

$ curl -vk https://localhost:8000/health
*   Trying 127.0.0.1:8000...
* Connected to localhost (127.0.0.1) port 8000 (#0)
* ALPN, offering h2
* SSL connection using TLSv1.3
> GET /health HTTP/1.1
> Host: localhost:8000
> User-Agent: curl/8.5.0
> Accept: */*
<
< HTTP/1.1 200 OK
< content-type: application/json
< content-length: 45
<
{"status":"ok","timestamp":"2025-09-16T12:34:56Z"}

Sampling Request with Auth

$ curl -vk -H "Authorization: Bearer mytesttoken" https://localhost:8000/sampling
*   Trying 127.0.0.1:8000...
* Connected to localhost (127.0.0.1) port 8000 (#0)
* ALPN, offering h2
* SSL connection using TLSv1.3
> GET /sampling HTTP/1.1
> Host: localhost:8000
> User-Agent: curl/8.5.0
> Accept: */*
> Authorization: Bearer mytesttoken
<
< HTTP/1.1 200 OK
< content-type: application/json
< content-length: 38
<
{"result":"sampled","value":42}

Tool Invocation (File Read)

$ curl -vk -H "Authorization: Bearer mytesttoken" -X POST https://localhost:8000/toolInvocation -d '{"tool":"fs.read","args":{"path":"/tmp/example.txt"}}'
*   Trying 127.0.0.1:8000...
* Connected to localhost (127.0.0.1) port 8000 (#0)
* ALPN, offering h2
* SSL connection using TLSv1.3
> POST /toolInvocation HTTP/1.1
> Host: localhost:8000
> User-Agent: curl/8.5.0
> Accept: */*
> Authorization: Bearer mytesttoken
> Content-Type: application/json
> Content-Length: 68
<
< HTTP/1.1 200 OK
< content-type: application/json
< content-length: 38
<
{"content":"Hello from file system!"}

File Structure

Self-hosted MCP Server for Local AI Agent Orchestration/
  src/          # Core source code
    main.py     # Application entry point
    config.py   # Pydantic settings loader
    security.py # TLS and auth utilities
    mcp/        # MCP protocol handling
      handler.py# Message routing and dispatch
  tests/        # Test suite
    test_main.py
    test_docker.py
    test_integration.py
  Dockerfile    # Builds python:3.11-slim image
  docker-compose.yml
  pyproject.toml# Dependencies and project metadata
  certs/        # TLS certificates (server.pem, server.key)
  README.md     # This file

Tech Stack

Technology	Purpose
Python 3.11+	Core language runtime
Click	CLI construction and entrypoint
Pytest	Test runner and test discovery
Pydantic	Settings validation and data modeling
asyncio	Asynchronous I/O and concurrency

Contributing

• Fork the repository
• Create a feature branch
• Make changes and add tests
• Submit a pull request

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio