Five Evolution Stages of an MCP Architecture

Overview: Evolution of the Architecture

The MCP server presented here in five evolution stages makes it possible to query an SQLite database in natural language through an MCP client such as Claude Code, or ChatGPT/Codex. The decisive prerequisite is a semantic model of the database rather than client-specific code. We keep that model in a self-contained YAML file, so the database-specific knowledge is cleanly separated from the generic MCP server. The user does not need SQL knowledge: the LLM interprets the task, uses the semantic description to understand the schema, determines the required tables and columns, generates the necessary SQL statements, and presents the result as a useful view of the data.

database:
  name: finance.db
  hint: Dezimaltrenner ist ein Punkt. Es gibt keinen Tausendertrenner. Währungseinheit ist EUR.
  description: Finanz-, Budget-, Vertrags-, Aufwands- und Zeitkartendaten
tables:
  Budgets: #{{{{
    description: Budgets für Teams je Projekt
    synonyms:
      - Budget
      - Geld
      - Mittel
      - Zuweisung
      - budgets
      - funds
      - allocation
    columns:
      tbwla:
        description: Bezeichner des Gremiums, zu welchem ein Projekt gehört.
      scopeid:
        description: Identifier eines Scope (reine Ziffernfolge)
        synonyms:
          - Projektnummer
          - project number
          - scope id
      scope:
        description: Name eines Projektes
        synonyms:
          - Projekt
          - project
          - project name
      team:
        description: Einheit, welcher genehmigtes, geplantes und verbrauchtes Budget zugeordnet sind
        synonyms:
          - Abteilung
          - senior-chapter
          - Referat
          - Chapter
          - Einheit
          - department
          - unit
          - organizational unit
          - chapter
      status:
        description: Status der Genehmigung eines Projektes
        synonyms:
          - approval status
          - project status
      fplegen:
        description: genehmigtes Budget (EUR netto)
        synonyms:
          - genehmigtes Budget
          - Soll
          - approved budget
          - authorized budget
      fpleav:
        description: geplantes, aber noch nicht genehmigtes Budget (EUR netto)
        synonyms:
          - geplantes Budget
          - Arbeitsversion
          - planned budget
          - unapproved budget
          - budget draft
      ist:
        description: verbrauchtes, gebuchtes Budget (EUR netto)
        synonyms:
          - Ist
          - Buchung
          - Verbrauch
          - actual
          - actuals
          - consumed budget
          - booked budget
          - budget consumption
      wbs:
        description: Zu scopeid alternativer Identifier eines Scope (Buchstaben, Ziffern, Bindestrich, Schrägstrich)
        synonyms:
          - wbs-Element
          - wbs-id
          - WBS element
          - WBS id
      scv:
        description: Scope-Verantwortlicher, d.h. Projektleiter
        synonyms:
          - Scope-Verantwortlicher
          - Projektleiter
          - scope owner
          - project manager
          - project lead
  #}}}}
  Chargings: #{{{{ 
    description: Gibt diejenigen Werte an, mit welchen Kosten aus Stundenmeldungen berechnet werden, wenn ein Mitarbeiter das Modell in Spalte model hat. Alle Zahlenformate sind englisch, mit einem Punkt als Dezimal- und keinem Tausendertrenner.
    use: false
  #}}}}
  Contracts: #{{{{
    synonyms:
      - Vertraege
      - contracts
      - agreements
    description: Tabelle aller Mitarbeiter und der Stammdaten eines Vertrages mit einem bestimmten Dienstleister oder Provider. Alle Zahlenformate sind englisch, mit einem Punkt als Dezimal- und keinem Tausendertrenner.
    columns:
      contract:
        synonyms:
          - Provider
          - Dienstleister
          - Firma
          - provider
          - service provider
          - vendor
          - company
        description: Bezeichner eines Vertrags. 
      resource:
        synonyms:
          - employee
          - staff member
          - consultant
          - user
        description: Vor und Nachname eines Mitarbeiters. Diese Spalte ist identisch mit Spalte user in Tabelle Resources.
      shore:
        synonyms:
          - shoring
          - onshore
          - nearshore
          - offshore
        description: Angabe, ob ein externer Mitarbeiter in Deutschland (onshore) oder einem als nearshore oder offshore klassifizierten Land arbeitet. Diese Spalte entspricht Spalte shore in Tabelle Resources.
      location:
        synonyms:
          - Land
          - country
          - location
          - work location
        description: Land, in welchem ein Mitarbeiter arbeitet
      role:
        synonyms:
          - job role
          - function
        description: Rollenbezeichnung eines Mitarbeiters, z.B. developer (Entwickler)
      category:
        synonyms:
          - role category
          - classification
        description: Klassifikation der Rolle des Mitarbeiters, z.B. ist SC7 eine Entwicklungstätigkeit
      skill:
        synonyms:
          - Befaehigung
          - Qualifikation
          - skill
          - qualification
          - proficiency level
        description: Befähigungsstufe, z.B. Expert
      year:
        synonyms:
          - contract year
        description: Jahr des Vertrags im Format yyyy
      dayrate_Eur:
        synonyms:
          - Tagessatz
          - day rate
          - daily rate
        description: Tagessatz netto in EUR. Das Zahlenformat ist englisch, mit einem Punkt als Dezimal- und keinem Tausendertrenner.
      volume_days:
        synonyms:
          - Volumen
          - Anzahl Tage
          - volume
          - number of days
          - contracted days
        description: Anzahl Tage des Mitarbeiters im jeweiligen Jahr des Vertrages. Das Format ist eine Ganzzahl.
      nettotal_Eur:
        synonyms:
          - Nettokosten
          - net costs
          - net total
          - total contract cost
        description: Gesamtkosten netto eines Mitarbeiters im jeweiligen Jahr des Vertrages als Produkt aus dayrate_Eur und volume_days. Englisches Zahlenformat mit Punkt als Dezimaltrenner und keinem Tausendertrenner.
      hourly_rate_Eur:
        synonyms:
          - Stundensatz
          - hourly rate
        description: Stundensatz netto eines Mitarbeiters im jeweiligen Jahr des Vertrages als Quotient aus dayrate_Eur und 8.0. Englisches Zahlenformat mit Punkt als Dezimaltrenner und keinem Tausendertrenner.
      resplan_hours:
        synonyms:
          - Ressourcenplan Stunden
          - resource plan hours
          - planned hours
        description: Anzahl Stunden, welche für den Mitarbeiter im System geplant werden müssen als Produkt aus volume_days und 8.0. Englisches Zahlenformat mit Punkt als Dezimaltrenner und keinem Tausendertrenner.
      transition_days:
        synonyms:
          - Übergangstage
          - transition days
          - free days
          - non-billable days
        description: Anzahl der sogenannten Übergangstage. Das sind unentgeltliche Tage.
      span:
        synonyms:
          - Spanne
          - contract duration
          - contract period
          - span
        description: Zeitdauer eines Vertrags in Jahren. Format ist entweder yyyy oder yyyy-yyyy
      gbuy:
        synonyms:
          - GBUY number
          - GBUY id
        description: sogenannte GBUY-Nummer eines Vertrages. Die GBUY-Nummer wurde bei Beantragung eines Vertrages vergeben.
      fglass:
        synonyms:
          - Fieldglass
          - Fieldglass-ID
          - Fieldglass number
          - Fieldglass id
        description: sogenannte Fieldglass-Nummer eines Vertrags
      fglass_approval:
        synonyms:
          - Fieldglass approval
          - Fieldglass approval date
        description: Datum der Fieldglass-Genehmigung. Zahlformat ist mm/dd/yyyy.
      pnumber:
        synonyms:
          - purchase order number
        description: sogenannte 'purchase order number' eines Vertrags. Das ist eine eindeutige ID, welche Spalte porder in Tabelle Efforts entspricht.
      porder: 
        synonyms:
          - purchase order
          - PO
        description: sogenannte 'purchase order' eines Vertrages. Diese Spalte ist nicht identisch mit Spalte porder in Tabelle Efforts.
      pol:
        synonyms:
          - purchase order line
          - purchase order line number
          - PO line
        description: sogenannte 'purchase order line number' eines Vertrages.
      srf_id:
        synonyms:
          - SRF id
          - SRF number
        description: sogenannte srf-id des sogenannten TPRM-Prozesses zu einem Vertrag
      tprm_id:
        synonyms:
          - TPRM id
          - TPRM number
        description: sogenannte TPRM-ID des TPRM-Prozesses zu einem Vertrag
      sourcing_project_id:
        synonyms:
          - sourcing id
          - sourcing project id
        description: sogenannte 'sourcing project id' eines Vertrages
      cw_id:
        synonyms:
          - workspace id
          - current workspace id
          - cw-id
          - Vertragsnummer
          - contract number
          - workspace id
          - current workspace id
        description: sogenannte "workspace id" eines Vertrages
      cw_id_master:
        synonyms:
          - workspace id des masters
          - current workspace id des masters
          - cw-id des masters
          - Rahmenvertragsnummer
          - master contract number
          - master workspace id
          - master current workspace id
        description: sogenannte "workspace id" des einem Vertrag übergeordneten Rahmenvertrages
      tprm_iso:
        synonyms:
          - information security officer
          - ISO
        description: Name des 'information security officers', welcher dem sogenannten TPRM-Prozess eines Vertrages zugeordnet ist
      procurement:
        synonyms:
          - purchasing
          - buyer
        description: Name des Mitarbeiters bei Einkauf (procurement), welcher für den Vertrag zuständig ist
      contact:
        synonyms:
          - account manager
          - provider contact
          - vendor contact
        description: Name des 'account managers' beim Vertragspartner (Provider, Dienstleister)
  #}}}}
  Contractscommon: #{{{{
    use : false
  #}}}}
  Efforts: #{{{{
    synonyms:
      - weekly efforts
      - Ablastung
      - Weiterverrechnung
      - weekly expenses
      - weekly charges
      - chargeback
      - cost allocation
    description: wöchentliche Aufwände je Mitarbeiter, welche dispatched oder noch nicht dispatched wurden. dispatched ist der Fachbegriff für weiterverrechnet. Jede Zeile entspricht der Ablastung eines (hier anonymisierten) Mitarbeiters. Alle Zahlenformate sind englisch mit einem Punkt als Dezimaltrenner und keinem Tausendertrenner.
    columns:
      division:
        synonyms:
          - Fachbereich
          - division
          - business unit
        description: Ein Fachbereich hat mehrere Abteilungen. Eine Abteilung hat mehrere Referate. Teams sind Mitarbeiter aus einem oder mehreren Referaten.
      department:
        synonyms:
          - Abteilung
          - department
        description:  Eine Abteilung hat mehrere Referate. Teams sind Mitarbeiter aus einem oder mehreren Referaten.
      team:
        description: Name für eine Gruppe von Mitarbeitern aus einem oder mehreren Referaten, welche an einem Projekt arbeiten
        synonyms:
          - Abteilung
          - senior-chapter
          - Referat
          - Chapter
          - Einheit
          - department
          - unit
          - organizational unit
          - chapter
      contract: 
        synonyms:
          - internal/external
          - employment type
          - worker type
        description: Angabe, ob ein Mitarbeiter intern oder extern ist
      shoring: 
        synonyms:
          - shore
          - onshore
          - nearshore
          - offshore
        description: Angabe, ob ein externer Mitarbeiter in Deutschland (ON) oder einem als nearshore (NEAR) oder offshore (OFF) klassifizierten Land arbeitet. Diese Spalte entspricht nicht Spalte shore in den Tabellen Contracts und Resources, denn sie hat andere Ausprägungen (OFF, NEAR, ON anstelle offshore, nearshore, onshore).
      topic: 
        synonyms:
          - contract type
          - billing type
          - time and material
          - fixed price
        description: Angabe, ob die Ablastung sich auf einen Time/Material-Vertrag (VAT) oder Fixpreisvertrag (Fixed Price) bezieht
      porder: 
        synonyms:
          - purchase order
          - PO
          - purchase order number
        description: sogenannte 'purchase order' eines Vertrags. Das ist eine eindeutige ID, welche Spalte pnumber, nicht Spalte porder in Tabelle Contracts entspricht. 
      provider:
        synonyms:
          - Dienstleister
          - Firma
          - service provider
          - vendor
          - company
        description: Name einer Firma, zu welcher ein externer Mitarbeiter gehört. Diese Spalte ist nicht identisch mit Spalte contract in Tabelle Contracts.
      todispatch:
        synonyms:
          - noch abzulasten
          - noch weiterzuverrechnen
          - to be dispatched
          - not yet dispatched
          - pending dispatch
          - pending chargeback
        description: Betrag, welcher noch abzulasten/weiterzuverrechnen ist. Das Zahlenformat ist englisch mit einem Punkt als Dezimaltrenner und keinem Tausendertrenner
      dispatched:
        synonyms:
          - abgelastet
          - weiterverrechnet
          - dispatched
          - already dispatched
          - charged back
          - allocated costs
        description: Betrag, welcher bereits abgelastet/weiterverrechnet wurde. Das Zahlenformat ist englisch mit einem Punkt als Dezimaltrenner und keinem Tausendertrenner
  # }}}}
  Resources: #{{{{
    use: false
  #}}}}
  Timecards: #{{{{
    synonyms:
      - Zeitkarten
      - Stundenbuchungen
      - timecards
      - timesheets
      - time bookings
      - hours booked
    description: Liste aller Stundenbuchungen je Mitarbeiter und Woche, der sogenannten Zeitkarten. Jede Zeile ist eine Zeitkarte, d.h. eine Wochenbuchung an Stunden.
    columns:
      month:
        synonyms:
          - month
          - booking month
        description: der Zeitkarte zugeordneter Monat im Format yyyy-mm
      week: 
        synonyms:
          - week
          - week start
          - week starting
        description: Anfangstag der Woche einer Zeitkarte im Format yyyy-mm-dd
      team:
        synonyms:
          - Abteilung
          - senior-chapter
          - Referat
          - Chapter
          - Einheit
          - department
          - unit
          - organizational unit
          - chapter
        description: Team, zu welchem ein Mitarbeiter gehört. Teams können sein Chapter, Referate, Abteilungen, Senior-Chapter oder Projektteams. 
      user: 
        synonyms:
          - resource
          - Mitarbeiter
          - Interner
          - Externer
          - employee
          - resource
          - staff member
          - internal employee
          - external employee
          - contractor
        description: Vorname und Nachname eines Mitarbeiters. 
      total: 
        synonyms:
          - hours
          - total hours
          - booked hours
        description: Anzahl Stunden der Zeitkarte. Gleitkommazahl mit englischem Dezimaltrenner und keinem Tausendertrenner.
      state:
        synonyms:
          - Status
          - state
          - booking status
          - approval status
        description: Status einer Buchung. Möglich sind folgende Statuswerte und deren Synonyme.
        values:
          pending: offen
          approved: genehmigt
          processed: verarbeitet
          disabled: verworfen, ungueltig
      rate:
        synonyms:
          - Tagessatz
          - dayrate
          - day rate
          - daily rate
        description: Tagessatz brutto in EUR. Dezimaltrenner ist ein Punkt. Kein Tausendertrenner.
      intext:
        synonyms:
          - internal/external
          - employee type
          - worker type
        description: Bezeichnung, ob ein Mitarbeiter intern (Angestellter der Allianz) oder extern (Vertrag bei einem Provider/Dienstleister) ist.
      shore: 
        synonyms:
          - shoring
          - onshore
          - nearshore
          - offshore
        description: Angabe, ob ein externer Mitarbeiter in Deutschland (onshore) oder einem als nearshore oder offshore klassifizierten Land arbeitet. Diese Spalte entspricht Spalte shore aus Tabelle Contracts.
      model:
        synonyms:
          - Modell
          - Abrechnungsmodell
          - Verrechnungsmodell
          - Typ
          - Variante
          - billing model
          - charging model
          - cost model
        description: Abrechnungsmodell. 
      contract:
        synonyms:
          - contract
          - agreement
        description: Name des Vertrags bei einem externen Mitarbeiter
      correction:
        synonyms:
          - Korrektur
          - Korrekturwert
          - Korrekturfaktor
          - correction
          - correction value
          - correction factor
        description: Korrekturwert zur Berechnung von Spalte charged
      app:
        synonyms:
          - Arbeitsplatzpauschale
          - workplace allowance
          - workplace charge
        description: Arbeitsplatzpauschale fällt bei externen Mitarbeitern je 8 Stunden an und dient der Berechnung von Spalte charged
      overhead:
        synonyms:
          - Zuschlag
          - overhead
          - surcharge
        description: Der Overhead dient der Berechnung von Spalte charged
      markup:
        synonyms:
          - markup
          - surcharge
        description: Das Markup dient der Berechnung von Spalte charged
      vat: 
        synonyms:
          - Mehrwertsteuer
          - MwSt
          - VAT
          - value added tax
        description: Die Mehrwertsteuer wird nicht verwendet
      charged:
        synonyms:
          - in Rechnung gestellt
          - gebucht
          - Kosten
          - Geldbetrag
          - charged
          - billed
          - invoiced
          - costs
          - amount charged
        description: In Rechnung gestellter Wert der Zeitkarte in der Einheit EUR als Gleitkommazahl mit englischem Dezimaltrenner und keinem Tausendertrenner.
  #}}}}

The YAML example above describes the semantic structure of a financial database and is independent of the Ancient Greek database used in the MCP implementation below. The running MCP example is a database for the conjugation of Ancient Greek verb classes. It consists of eight wide tables with the same basic structure, one table for each verb or conjugation class (paideuw, poiw, timw, doulw, diwkw, grafw, peithw, and angellw). The following image shows the first columns of the table for παιδεύω (paideuw) as they might be displayed on a conventional website.

The Five Evolution Stages

1. Stage 1 · Local MCP / Local DB (generic): A local MCP client (Claude Code) calls a locally started Python MCP server. The MCP server exposes the database structure; the LLM interprets the natural-language request, translates it into SQL, and queries the local SQLite database directly.

   

2. Stage 2 · Local MCP / Remote DB (limited): A local MCP client still calls a locally started Python MCP server. The natural-language task is interpreted and a remote CGI script is called with only two parameters: a list of required tables and a list of required columns. The SQL logic resides entirely in the CGI script.

   

3. Stage 3 · Local MCP / Remote DB (generic): The local MCP client uses a locally started Python MCP server that is now schema-independent. Through this server, the LLM discovers the table structure, creates the SQL statement, and sends it to a remote CGI script that executes it against the SQLite database there.

   

4. Stage 4 · Remote MCP / Remote DB (generic): No local MCP server is installed on the MCP client. Only the MCP configuration and access token remain on the client. The complete MCP server runs on the remote web server; Claude uses it to discover the schema and SQL and lets it query the database directly.

   

5. Stage 5 · Consolidated Multi-Database MCP: The database-specific remote MCP processes are consolidated into one Python environment, one server process, one systemd service, and one local TCP port. A central database.yaml maps logical endpoint names to the corresponding SQLite database and semantic YAML file. Apache keeps the public per-database URLs and authentication boundaries, but routes them to separate MCP mounts inside the same process.
   MCP clients/mcp/journal · /mcp/finance · …

   HTTPS→

   Apache :443TLS · Bearer tokens · routing

   reverse proxy→

   127.0.0.1:8768one systemd service

   mounted MCP endpoints→

   Generic server.pyone venv · many MCP mounts

   database.yaml→

   SQLite + semanticsdatabase-specific files only

The five variants therefore show a gradual separation of client, MCP protocol, data access, and web infrastructure. At the same time, the MCP implementation becomes increasingly generic: first the schema knowledge is moved into a semantic YAML model; finally even the database-specific server processes disappear and are replaced by declarative entries in a central database.yaml.

SELECT
    p."Präsens Indikativ",
    t."Präsens Indikativ"
FROM poiw AS p
JOIN timw AS t ON t.rowid = p.rowid;

/usr/local/bin/verbs-mcp-server

/usr/local/lib/verbs-mcp/
    server.py
    .venv/

/usr/local/share/verbs-mcp/
    verbsdynamic.db

Project directory:
    .mcp.json

#!/usr/bin/env python3
"""Minimal read-only MCP server for verbsdynamic.db."""

from __future__ import annotations

import json
import os
import re
import sqlite3
from pathlib import Path
from typing import Any

from mcp.server import MCPServer

SERVER_NAME = "verbsdynamic"
DEFAULT_DB = Path("/usr/local/share/verbs-mcp/verbsdynamic.db")
DB_PATH = Path(os.environ.get("VERBSDYNAMIC_DB", str(DEFAULT_DB)))
MAX_ROWS = 200

mcp = MCPServer(SERVER_NAME)

ROW_SEMANTICS = {
    1: "1. Person Singular",
    2: "2. Person Singular",
    3: "3. Person Singular",
    4: "1. Person Plural",
    5: "2. Person Plural",
    6: "3. Person Plural",
}


def _connect() -> sqlite3.Connection:
    if not DB_PATH.is_file():
        raise RuntimeError(f"SQLite database not found: {DB_PATH}")

    # URI mode=ro makes the database read-only at SQLite level.
    con = sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True)
    con.execute("PRAGMA query_only = ON")
    con.set_authorizer(_authorizer)
    return con


def _authorizer(action: int, arg1: str | None, arg2: str | None,
                dbname: str | None, source: str | None) -> int:
    """Allow only operations needed for SELECT queries."""
    allowed = {
        sqlite3.SQLITE_SELECT,
        sqlite3.SQLITE_READ,
        sqlite3.SQLITE_FUNCTION,
    }
    if hasattr(sqlite3, "SQLITE_RECURSIVE"):
        allowed.add(sqlite3.SQLITE_RECURSIVE)
    return sqlite3.SQLITE_OK if action in allowed else sqlite3.SQLITE_DENY


def _first_sql_keyword(sql: str) -> str:
    """Return first SQL keyword after leading whitespace/comments."""
    s = sql.lstrip()
    while True:
        if s.startswith("--"):
            nl = s.find("\n")
            s = "" if nl < 0 else s[nl + 1:].lstrip()
            continue
        if s.startswith("/*"):
            end = s.find("*/", 2)
            if end < 0:
                return ""
            s = s[end + 2:].lstrip()
            continue
        break
    m = re.match(r"([A-Za-z]+)", s)
    return m.group(1).upper() if m else ""


def _schema_dict() -> dict[str, Any]:
    with _connect() as con:
        tables = [
            row[0]
            for row in con.execute(
                "SELECT name FROM sqlite_master "
                "WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
            )
        ]

        result: dict[str, Any] = {
            "database": str(DB_PATH),
            "semantics": {
                "one_table_per_verb": True,
                "rowid": ROW_SEMANTICS,
                "important": (
                    "All verb tables have the same column layout. "
                    "There is no explicit id/person column. SQLite rowid 1..6 "
                    "means 1sg, 2sg, 3sg, 1pl, 2pl, 3pl respectively. "
                    "Join different verb tables on rowid when comparing persons."
                ),
            },
            "tables": {},
        }

        for table in tables:
            quoted = table.replace('"', '""')
            cols = [
                {"name": row[1], "type": row[2] or ""}
                for row in con.execute(f'PRAGMA table_info("{quoted}")')
            ]
            count = con.execute(f'SELECT count(*) FROM "{quoted}"').fetchone()[0]
            result["tables"][table] = {"rows": count, "columns": cols}

        return result


@mcp.resource("verbs://schema", mime_type="application/json")
def database_schema_resource() -> str:
    """Schema and row semantics of the Ancient Greek verb database."""
    return json.dumps(_schema_dict(), ensure_ascii=False, indent=2)


@mcp.tool()
def get_database_schema() -> dict[str, Any]:
    """Return all verb tables, columns and row semantics before writing SQL.

    Use this when the user's question requires database access and the exact
    table/column names are not already known. Each table represents one verb.
    rowid 1..6 corresponds to 1sg, 2sg, 3sg, 1pl, 2pl, 3pl.
    """
    return _schema_dict()


@mcp.tool()
def query_sql(sql: str) -> dict[str, Any]:
    """Execute one read-only SELECT/WITH query against the verb database.

    The database contains one table per verb and equal schemas across tables.
    Use quoted identifiers for German column names, e.g.
    SELECT rowid, "Präsens Indikativ" FROM poiw ORDER BY rowid.
    To compare verbs, join tables on rowid. Only SELECT or WITH is accepted.
    At most 200 result rows are returned.
    """
    keyword = _first_sql_keyword(sql)
    if keyword not in {"SELECT", "WITH"}:
        raise ValueError("Only SELECT or WITH queries are allowed")

    with _connect() as con:
        cur = con.execute(sql)
        columns = [d[0] for d in cur.description] if cur.description else []
        rows = cur.fetchmany(MAX_ROWS + 1)

    truncated = len(rows) > MAX_ROWS
    if truncated:
        rows = rows[:MAX_ROWS]

    return {
        "columns": columns,
        "rows": [list(row) for row in rows],
        "row_count": len(rows),
        "truncated": truncated,
        "max_rows": MAX_ROWS,
    }


if __name__ == "__main__":
    mcp.run(transport="stdio")

Stage 4 removed the MCP server from the client, but each database still required its own Python virtual environment, server process, systemd unit, local port, and database-specific process configuration. Stage 5 removes this remaining operational duplication. All databases are served by one generic server.py in one virtual environment and by one mcp.service listening on a single local port.

Internet / MCP clients
  Claude Code · ChatGPT/Codex
              |
              | HTTPS :443
              v
+-------------------------------------------+
| Apache HTTP Server                        |
| TLS termination · Bearer auth · routing   |
+-------------------------------------------+
      |                         |
      | ProxyPass               | ProxyPass
      | /mcp/journal            | /mcp/finance
      v                         v
      http://127.0.0.1:8768/journal/mcp
      http://127.0.0.1:8768/finance/mcp
              \                       /
               \                     /
                v                   v
+---------------------------------------------------------+
| Uvicorn                                                  |
| own HTTP web server, bound only to 127.0.0.1:8768       |
| speaks ASGI to the Python application                    |
+---------------------------------------------------------+
                          |
                          | ASGI
                          v
+---------------------------------------------------------+
| Starlette application                                   |
| routes /journal and /finance to mounted ASGI subapps    |
|                                                         |
|  /journal  -----------------> MCPServer("journal")       |
|       /mcp                     |                        |
|                                +--> journal.yaml         |
|                                +--> journal.db           |
|                                                         |
|  /finance  -----------------> MCPServer("finance")       |
|       /mcp                     |                        |
|                                +--> finance.yaml         |
|                                +--> finance.db           |
|                                                         |
|  /...      -----------------> one MCPServer per DB       |
+---------------------------------------------------------+
                          ^
                          |
                 database.yaml registry
                 (name -> DB + semantics)

Apache :443
   | reverse proxy
   v
Uvicorn 127.0.0.1:8768
   | ASGI
   v
Starlette application

HTTP socket
   |
Uvicorn
   |  ASGI protocol boundary
Starlette
   |
mounted MCP ASGI applications

for cfg in configs:
    mcp = create_mcp(cfg)
    subapp = mcp.streamable_http_app(...)
    routes.append(Mount(f"/{cfg.name}", app=subapp))

Starlette(routes=routes, lifespan=lifespan)
       |
       +-- /journal --> journal MCP subapp --> /mcp
       +-- /finance --> finance MCP subapp --> /mcp
       +-- /...     --> ... MCP subapp     --> /mcp

databases:
  journal:
    database: /var/www/html/Private/Gruppe_1/journal.db
    semantics: /var/www/html/Private/Gruppe_1/journal.yaml

  finance:
    database: /var/www/html/Private/finance.db
    semantics: /var/www/html/Private/finance.yaml

/journal/mcp  → journal.db + journal.yaml
/finance/mcp  → finance.db + finance.yaml
/.../mcp      → ...

ProxyPass "/mcp/journal" \
  "http://127.0.0.1:8768/journal/mcp"

ProxyPass "/mcp/finance" \
  "http://127.0.0.1:8768/finance/mcp"

/usr/local/lib/mcp/
    .venv/
    server.py
    database.yaml
    requirements.txt

/etc/systemd/system/
    mcp.service

one local port:
    127.0.0.1:8768

Advantages over the previous remote MCP deployment

Installation Steps for the Consolidated Variant

1. Install the shared MCP package once

   tar xzf mcp.tgz
   cd mcp
   sudo ./install.sh

2. Register all databases centrally

   Edit /usr/local/lib/mcp/database.yaml and add one logical entry for every SQLite database and its semantic YAML file.

3. Configure Apache routes

   Keep the public URLs and per-database Bearer-token rules, but proxy every URL to its corresponding mount on the single local MCP port.

   /mcp/journal → 127.0.0.1:8768/journal/mcp
   /mcp/finance → 127.0.0.1:8768/finance/mcp

4. Start the single systemd service

   sudo systemctl enable --now mcp
   systemctl status mcp

5. Retire the old per-database services

   After the corresponding endpoints have been verified, the former database-specific MCP services, virtual environments, and local ports are no longer required.

Read-only and Operational Protection

Direct Comparison