MCP Blueprint

Build domain-oriented MCP servers without writing Python code.

MCP Blueprint is a lightweight framework for creating Model Context Protocol (MCP) servers from configuration files, SQL queries and metadata instead of custom application code.

Supports PostgreSQL, MySQL, Oracle, ClickHouse, SQL Server, SQLite and DuckDB.

Exposes curated business tools, not a generic SQL interface.

---

Why?

Many existing MCP database servers expose generic tools such as execute_sql() or query_database(). Although powerful, they require the LLM to understand the schema, write efficient SQL, know relationships between tables and respect business rules — a risky approach for production environments.

MCP Blueprint follows a different philosophy:

Don't expose the database. Expose the domain.

The LLM should ask for information, not write SQL.

---

Key features

• Domain-oriented — expose curated business tools, not a generic SQL interface.
• Production-ready — connection pooling, caching, parameter validation and error handling; stdio and Streamable HTTP support, Docker support.
• Configuration-driven — build MCP servers from YAML and SQL, without writing Python code.
• Multi-engine — one framework for PostgreSQL, MySQL, MariaDB, Oracle, ClickHouse, SQL Server, SQLite and DuckDB, with reference DBA packs already available.
• Safe by default — injection-proof parameters, read-only SQL, writes only behind an explicit opt-in.
• Built-in observability — structured JSON logging, audit trail with trace_id, optional Prometheus metrics.
• Per-tool caching — optional in-memory cache with a TTL configurable per tool (cache.ttl) and a server-wide default (server.default_ttl).
• Reusable packs — independent, versionable tool collections.

---

Getting started

Install the framework and run the reference server:

uv sync --all-extras --dev
uv run blueprint serve --config config --transport stdio

Or run it in Docker with a bundled PostgreSQL over Streamable HTTP:

docker compose up --build

The server is then available at http://localhost:8000/mcp.

See docs/installation.md, docs/quickstart.md and docs/docker.md for the full walkthrough.

---

Architecture

                 +----------------+
                 |    LLM Agent   |
                 +--------+-------+
                          |
                     MCP Protocol
                          |
                  +-------+-------+
                  | MCP Blueprint |
                  +-------+--------+
                          |
          +---------------+----------------+
          |               |                |
      Tool Metadata     SQL Loader     Logging
          |               |
          +-------+-------+
                  |
            Target database

The framework is responsible for creating MCP tools, parameter validation, database connections, logging, error handling and optional caching. Application developers only provide configuration files.

---

Reference packs

MCP Blueprint ships ready-to-use packs for every major database:

• six server DBA packs — PostgreSQL, MySQL, MariaDB, Oracle, ClickHouse, SQL Server;
• two embedded packs — SQLite and DuckDB, for file databases that need no server;
• a smoke pack — zero-dependency, runs on an in-memory SQLite database to verify a deployment end to end.

The DBA packs expose the same tools whatever the engine, so a prompt written for one database also works against the others (see docs/quickstart.md).

But the real point is packs/sakila: it synthesizes the domain into five tools resolved by name — recommend films, check stock, review a customer's account — while business logic (standing flags, overdue status, popularity) lives in SQL. The AI Agent just asks. In a comprehensive "model demotion" experiment this design reached 94% correct answers across four small local models, versus 67% for a generic read-only SQL agent. That is what a well-synthesized domain looks like.

Engine selection, driver extras and pack authoring are covered in docs/quickstart.md, docs/installation.md and docs/pack_development.md.

---

Tool design

An MCP server should look like a REST API, not like a SQL console: each tool represents a meaningful operation and hides all SQL complexity.

# Instead of
execute_sql(...)

# expose
search_customer()
get_database_sizes()
get_performance_kpis()

Beyond the tool API, MCP Blueprint owns the operational concerns — SQL safety (read-only by default, explicit opt-in for writes, injection-proof parameters), structured logging and telemetry — so pack authors never have to implement them; see the security model, logging, audit and tracing and Prometheus metrics.

---

Project structure

mcp-blueprint/
    blueprint/     # the framework
    config/        # server, database, logging, metrics YAML
    packs/         # the reference packs (8 DBA + sakila + smoke)
    examples/      # small example packs and client configs
    template/      # skeleton for authoring new packs
    docs/
    tests/

Each pack is self-contained: tools, SQL and metadata only, with the engine declared once in pack.yaml. No Python code is required to create a new tool.

---

Documentation

• Quick start
• Installation
• Pack development guide
• Sakila pack
• Smoke Test pack
• Docker
• Tutorial
• Logging, audit and tracing
• Prometheus metrics
• Best practices
• FAQ

---

Long-term vision

MCP Blueprint aims to become for MCP what REST frameworks became for HTTP APIs: developers describe their domain with SQL, and an MCP server is assembled from reusable packs rather than developed from scratch.

---

License

Released under the Apache License 2.0.