Secure MCP Server Template

Secure MCP Server Template

A minimal, correct, and security-first Model Context Protocol (MCP) server in Python. It exposes three example tools to any MCP client (Claude Desktop, Claude Code, etc.) — each one shipped with the security guard it actually needs.

Most "MCP server" tutorials show you how to expose a tool. They skip the part that matters once a model has real hands on your database, network, and disk. This template is built around that gap: how to give an LLM capabilities without opening a hole.

LLM client ──MCP──> this server ──> [ PostgreSQL | HTTP | filesystem ]
                         │
                         └── every tool passes through guards.py (tested)

What is MCP, in one paragraph

MCP is an open protocol that lets an AI client call external "tools" (functions) and read "resources" through a standard interface. You run a small server that declares tools; the client (Claude Desktop, Claude Code, …) discovers them and the model calls them during a conversation. It's the clean way to give a model access to your data and actions instead of pasting everything into the prompt.

Tools

| Tool | What it does | Guard | |---|---|---| | db_query(sql) | Run a read-only SQL query against DATABASE_URL, returns rows as JSON | SELECT/WITH only and a real READ ONLY Postgres session | | http_get(url) | HTTP GET, returns the body as text | http/https only + host allowlist, deny-by-default (anti-SSRF) | | read_file(path) | Read a text file under MCP_FILES_ROOT | Path resolved inside the root, blocks ../ traversal & absolute paths |

Security design (the point of this template)

• db_query can't write. Two layers: a static check (is_safe_select — rejects writes, DDL, and stacked ; statements) and the connection is opened READ ONLY, so even a clever bypass can't mutate data.
• http_get can't be turned into an SSRF. Only http(s), and the host must be in MCP_URL_ALLOWLIST. Empty allowlist = nothing allowed (deny-by-default), so a misconfigured server isn't an open proxy.
• read_file can't escape its root. Paths are resolved and checked to live inside MCP_FILES_ROOT; ../, absolute paths, and symlink escapes raise.

All three guards live in guards.py (zero dependencies) and are covered by tests/test_guards.py, so they run without even installing MCP.

Quickstart

git clone <this repo> && cd mcp-server-template
python -m venv .venv && . .venv/Scripts/activate   # (Linux/mac: . .venv/bin/activate)
pip install -e .            # add: pip install -e ".[db]" for PostgreSQL
cp .env.example .env        # edit with your values
python server.py            # runs over stdio

Use it from Claude Desktop

Add to your claude_desktop_config.json (see claude_desktop_config.example.json):

{
  "mcpServers": {
    "atelier-template": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": { "MCP_URL_ALLOWLIST": "api.github.com", "MCP_FILES_ROOT": "/safe/dir" }
    }
  }
}

Restart Claude Desktop; the three tools appear. (For Claude Code: claude mcp add atelier-template -- python /abs/path/server.py.)

Add your own tool (the 5-line version)

@mcp.tool()
def word_count(text: str) -> str:
    """Count words in a string."""   # <- this docstring is what the model reads
    return str(len(text.split()))

That's the whole loop: decorate a function, write a clear docstring (the model uses it to decide when/how to call), return a string. If the tool touches data/network/disk, add a guard — that's the habit this template is trying to teach.

Layout

server.py     # the MCP server + 3 example tools
guards.py     # pure, dependency-free security helpers (tested)
tests/        # pytest for the guards (run without mcp installed)
.env.example  # configuration

Tests

pip install pytest && pytest -q

License

MIT © 2026 Eduardo Pérez Ignacio