A minimal template for running an MCP (Model Context Protocol) server with support for authentication, PostgreSQL integration, and containerization. Built using FastMCP.
- 🔑 Basic Authentication (via API token)
- 🗄 PostgreSQL database integration
- 🌐 HTTP server for MCP transport
- 📦 Containerization with Docker & Docker Compose
- 🗄 Migrations for database schema management
docker compose upNote: You will need to set environment variables in your system
docker build -t mcp-server .
docker run -p 8000:8000 mcp-serverNote: You will need to set environment variables in .env file.
Running project locally will require python 3.11 or higher.
uv sync -Install packages. Read more about it here.
cd src - move to project root
python -m server - run server (don't forget to set .env file)
The server is configured using environment variables.
| Variable | Required | Description |
|---|---|---|
API_TOKEN |
❌ | API token for basic authentication. If provided, clients must include it in requests. |
DATABASE_URL |
✅ | PostgreSQL connection string. Format: postgresql://user:password@localhost:5432/mydb |
👉 When working locally, create a .env file in the project root (use .env.example as a template).
- Local:
http://localhost:8000 - Remote:
http://<your-server-domain>
If API_TOKEN is set, include it in your request headers:
Authorization: Bearer ${API_TOKEN}
Content-Type: application/json
Accept: application/json, text/event-stream
get me record from table data where id is 3get me all records from table dataget me all records from table data where name is "John Doe"
- ✅ Currently supports:
streamable-http - 🚧 Can be extended to support other MCP transports
flowchart TD
A[MCP Client] <-- streamable-http --> B[MCP Server]
B <-- queries --> C[(PostgreSQL Database)]
A -. Call with instructions and headers .-> B:::auth
- MCP Client communicates with the server using HTTP (
streamable-http). - MCP Server handles authentication and queries.
- PostgreSQL Database stores and retrieves persistent data.
- Optional API Token can be used for secured communication.
sequenceDiagram
participant Client as MCP Client
participant Server as MCP Server
participant DB as PostgreSQL Database
Client->>Server: HTTP Request (with headers & optional Bearer Token)
Server->>Server: Validate API Token (if required)
alt Token invalid
Server-->>Client: 401 Unauthorized
else Token valid / not required
Server->>DB: Execute query
DB-->>Server: Query result
Server-->>Client: Response (JSON / Event Stream)
end