MCP Blueprint

Build domain-oriented MCP servers without writing Python code for every project.

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. Instead of exposing a generic SQL interface, it exposes a curated set of business-oriented tools that are easier for LLMs to understand, safer to use and simpler to maintain.

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.
• Configuration-driven — build MCP servers from YAML and SQL, without writing Python code for every project.
• Multi-engine — one framework for PostgreSQL, MySQL, MariaDB, Oracle, ClickHouse, SQL Server, SQLite and DuckDB, with reference DBA packs already available.
• Safe by default — read-only SQL, injection-proof parameters, writes only behind an explicit opt-in.
• Built-in observability — structured JSON logging, an 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).
• Production-ready — connection pooling, caching, parameter validation and error handling; Docker and Streamable HTTP support.
• 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.

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 agent just asks. In an internal "model demotion" experiment this design reached 98% fully-correct answers across four small local models, versus 0.711 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
get_customer()
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)
    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
• 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, and an MCP server is assembled from reusable packs rather than developed from scratch.

License

Released under the Apache License 2.0.