mcp-server-suite

A hardened Model Context Protocol (MCP) server that speaks JSON-RPC 2.0 over standard I/O and exposes three narrowly scoped tools:

The server is designed to be launched by an MCP client as a child process, inside an unprivileged container with a read-only root filesystem.

Design tenets

• Fail closed. Every input crosses a strict schema (extra="forbid", strict types, no NaN/Infinity). Anything the policy does not explicitly allow is rejected with a machine-readable RFC 9457 problem.

• Structured concurrency. One asyncio.TaskGroup owns every task in a session. Each tools/call is a child task that can be cancelled, deadline-bounded and drained on shutdown. No task outlives the session.

• No runtime network dependencies. The transport is stdio. The only outbound connection the server can make is to the PostgreSQL DSN you configure, and the shipped Compose profile has networking disabled.

• Defence in depth. Each control assumes the one before it failed. The SQL AST policy is backed by read-only transactions and a least-privilege role. Path resolution is backed by a race-free openat walk. The container adds a non-root UID, no capabilities and an immutable root filesystem.

Related MCP server: rag-mcp-agent-demo

Contents

• Quickstart

• Architecture

• Session lifecycle and concurrency

• Wire specification

• Tool contracts

• Error model

• Threat model (STRIDE)

• Configuration

• Operations

• Repository layout

• Contributing

• License

Quickstart

# Container (recommended)
docker compose build
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"cli","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' |
  docker compose run --rm -T mcp-server

# From source (Python 3.12, uv)
uv sync
mkdir -p data
MCP_SAFE_DATA_DIR="$PWD/data" uv run mcp-server-suite

The server reads requests from stdin until EOF or SIGINT/SIGTERM. Responses go to stdout and logs go to stderr.

Architecture

flowchart TB
    client["MCP client<br/>(parent process)"]

    subgraph proc["mcp-server-suite process: UID 10001, read-only rootfs, no capabilities"]
        direction TB
        stdio["Framed stdio<br/>newline-delimited JSON, 1 MiB ceiling,<br/>oversized lines dropped while streaming"]
        guard["Protocol guard<br/>strict UTF-8 JSON-RPC 2.0, no batches,<br/>no NaN, no duplicate keys, typed ids"]
        dispatch["Strict dispatcher<br/>lifecycle state, method routing,<br/>tools/call envelope, tool lookup"]

        subgraph rails["Guardrails: one TaskGroup task per tools/call"]
            direction TB
            san["Structural sanitizer<br/>identifier keys, depth 8, 1000 items,<br/>control, bidi and surrogate code points"]
            lim["Concurrency limiter<br/>16 slots, FIFO, 5 s bounded wait"]
            dl["Execution deadline<br/>30 s asyncio.timeout"]
            schema["Strict argument schema<br/>Pydantic v2, extra=forbid"]
        end

        subgraph tools["Isolated tools"]
            sql["read_only_sql<br/>sqlglot AST policy"]
            fs["sandbox_fs_read<br/>openat + O_NOFOLLOW walk"]
            met["system_metrics<br/>psutil in worker thread"]
        end
    end

    pg[("PostgreSQL<br/>SELECT-only role")]
    data[("/safe_data_dir<br/>read-only mount")]
    host[("/proc")]

    client -- "stdin" --> stdio --> guard --> dispatch
    dispatch -- "initialize, ping, tools/list<br/>answered inline" --> client
    dispatch -- "tools/call" --> san --> lim --> dl --> schema
    schema --> sql
    schema --> fs
    schema --> met
    sql -- "BEGIN READ ONLY, always rolled back" --> pg
    fs --> data
    met --> host
    tools -- "stdout: ASCII-only JSON frames" --> client

Session lifecycle and concurrency

sequenceDiagram
    autonumber
    participant C as MCP client
    participant L as Read loop
    participant T as tools/call tasks
    participant OS as Signals

    C->>L: initialize (protocolVersion 2025-11-25)
    L-->>C: result: protocolVersion, capabilities.tools, serverInfo
    C-)L: notifications/initialized
    C->>L: tools/list
    L-->>C: result: tools with inputSchema, outputSchema, annotations

    par Concurrent calls
        C->>L: tools/call id=7 system_metrics
        L->>T: spawn task 7 in the TaskGroup
        Note over T: sanitize, acquire slot, run under deadline
        T-->>C: result id=7: structuredContent, isError false
    and
        C->>L: tools/call id=8 read_only_sql
        L->>T: spawn task 8
        C-)L: notifications/cancelled requestId=8
        L->>T: cancel task 8
        Note over T,C: A cancelled request receives no response
    end

    OS->>L: SIGTERM or SIGINT
    L->>L: stop reading stdin
    L->>T: drain in-flight calls (5 s grace)
    alt Second signal or grace period expires
        L->>T: cancel remaining tasks
    end
    L-->>C: flush and close stdout, exit 0

• initialize, ping and tools/list are answered inline, in arrival order. Each tools/call runs as its own task, so a slow tool never blocks the read loop and responses may arrive out of order (match them by id).

• notifications/cancelled cancels the matching task. Per the MCP specification, a cancelled request gets no response.

• EOF on stdin, SIGINT and SIGTERM all start the same graceful drain. A second signal cancels in-flight work immediately. A write failure on stdout (client gone) also triggers shutdown.

• Blocking work (file reads, CPU sampling) runs in worker threads via asyncio.to_thread, so it never stalls the event loop.

Wire specification

Transport. One JSON-RPC 2.0 message per line (\n-terminated, an optional trailing \r is tolerated, blank lines are ignored). The maximum frame size is 1 MiB (1,048,576 bytes). Larger lines get a -32600 error with "data": {"max_frame_bytes": 1048576} and the session continues.

Protocol versions. 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. A client requesting any other version is offered 2025-11-25, per the MCP negotiation rules.

Unknown notifications are ignored. Unknown methods return -32601. Responses sent by the client are ignored, because the server issues no requests of its own.

Tool contracts

Every tool is advertised with readOnlyHint: true, destructiveHint: false, idempotentHint: true and openWorldHint: false. Successful calls return the result as both JSON structuredContent and an identical JSON text block.

read_only_sql

Registered only when MCP_SQL_DSN is set.

How a query is enforced:

1. Single statement. The query is parsed with sqlglot (PostgreSQL dialect). More than one statement is a MCP_QUERY_VIOLATION.

2. Root and tree policy. The root must be a SELECT or a set operation (UNION/INTERSECT/EXCEPT). The entire AST is walked, so a write hidden in a CTE (WITH d AS (DELETE …) SELECT …) is rejected. Rejected nodes include DML, DDL, DROP, ALTER, TRUNCATE, GRANT/REVOKE, SET, transaction control, SELECT INTO, row locks (FOR UPDATE) and anything sqlglot models only as an opaque command (DO, CALL, COPY, VACUUM, …).

3. Function denylist. Functions with effects that survive a rolled-back read-only transaction are rejected: dblink*, lo_*, advisory locks, pg_sleep, pg_read_file, pg_ls_*, pg_terminate_backend, set_config, pg_notify, replication and WAL control, among others. Bind parameters are rejected (inline literals instead).

4. Deterministic LIMIT. The outer LIMIT is rewritten to min(literal, max_rows). A missing, non-literal, ALL, PERCENT or WITH TIES limit becomes LIMIT max_rows. The SQL actually executed is regenerated from the validated AST (comments dropped) and validated a second time.

5. Execution. The query runs inside BEGIN READ ONLY with a transaction-local statement_timeout, and the transaction is always rolled back. Pooled connections also default to default_transaction_read_only=on.

PostgreSQL errors caused by the query are mapped in-band: 57014 (statement timeout) to MCP_EXECUTION_TIMEOUT, 25006 (read-only violation) to MCP_QUERY_VIOLATION, 42501 to MCP_ACCESS_DENIED, and SQLSTATE classes 21, 22, 42, 0A and 54 to MCP_VALIDATION_ERROR. Connection and server failures are infrastructure faults (-32603).

sandbox_fs_read

Registered only when MCP_SAFE_DATA_DIR is set (the container image sets it to /safe_data_dir).

How a read is enforced:

1. Canonical containment. (root / relative_path).resolve() follows every symlink and the result must satisfy is_relative_to(root). Resolution is non-strict, so a path outside the sandbox is denied whether or not it exists (no existence oracle). Symlink loops are rejected.

2. Race-free open. The resolved path is re-opened one component at a time with openat relative to a directory fd, using O_NOFOLLOW on every component. A directory swapped for a symlink between steps 1 and 2 fails with ELOOP and cannot escape. Symlinks that resolve inside the sandbox are followed by step 1, so the walk itself never meets one.

3. File type. The leaf is opened O_NONBLOCK | O_NOCTTY and checked with fstat on the open descriptor. Only regular files are read. FIFOs, sockets and character or block devices are denied, and a FIFO cannot hang the worker.

4. Bounded read. At most max_bytes + 1 bytes are read, in a worker thread, then strictly decoded.

5. No path leaks. Problems echo at most 256 characters of the caller's own relative_path and never an absolute host path.

system_metrics

Registered unless MCP_METRICS_ENABLED=false.

Readings are clamped into range, because containers and VMs occasionally report slightly out-of-range values. The disk path is configuration only and is never echoed back.

Error model

MCP distinguishes two failure channels, and this server uses them deliberately:

• In-band tool errors (result.isError: true). The tool ran (or was refused) because of what the caller asked for: invalid arguments, a policy violation, a denied path, a timeout or a full concurrency queue. The result carries one text block whose content is an RFC 9457 problem document. The calling model can read it, correct the arguments and retry. structuredContent is omitted because it would not match the tool's outputSchema.

• Transport-level JSON-RPC errors (error). The message is wrong rather than the tool call: unparsable JSON, an invalid envelope, an unknown method, a call before initialize, an unknown tool name or a malformed tools/call envelope. Unexpected crashes inside a tool also land here as -32603. The traceback goes to stderr and the client sees only a generic message.

The JSON-RPC code is used when a problem travels as error.data, for example an unknown tool name, which is reported as -32602 with the problem attached. type and status are validated against the code, so the same code can never be emitted with conflicting semantics. The other JSON-RPC codes are the standard ones: -32700 parse error, -32600 invalid request, -32601 method not found.

In-band error (path traversal attempt):

{"jsonrpc":"2.0","id":3,"result":{"isError":true,"content":[{"type":"text",
 "text":"{\"type\": \"urn:mcp-server-suite:problem:access-denied\", \"title\": \"Access to the requested resource is denied\", \"status\": 403, \"detail\": \"'../../etc/passwd' resolves outside the sandbox\", \"code\": \"MCP_ACCESS_DENIED\", \"invalid_params\": [\"relative_path\"], \"metadata\": {}}"}]}}

Protocol error (unknown tool):

{"jsonrpc":"2.0","id":4,"error":{"code":-32602,"message":"Unknown tool: 'no_such_tool'",
 "data":{"type":"urn:mcp-server-suite:problem:validation-error","title":"Invalid tool arguments",
 "status":422,"detail":"Unknown tool: 'no_such_tool'","code":"MCP_VALIDATION_ERROR",
 "invalid_params":["name"],"metadata":{}}}}

Threat model (STRIDE)

Assets. Database contents and integrity, files on the host outside the sandbox, host availability, and the integrity of the published source.

Trust boundaries.

1. The MCP client and the model driving it, which supply all tool arguments. These are treated as untrusted, including prompt-injected input.

2. The process boundary, which the container hardens.

3. The PostgreSQL server.

4. The source supply chain (commits, dependencies, base images, CI actions).

MCP over stdio has no authentication of its own: whoever can spawn the process is the client. Access control is therefore the job of the launching environment, the mounted data and the database role.

Residual risks and limitations

• The SQL policy is a denylist over a parser's model of SQL, so it is a filter, not an isolation boundary. The database role is the boundary: give it SELECT on exactly the objects the model may see.

• A deadline cancels the awaiting task immediately, but Python cannot interrupt a worker thread. Thread work is kept short by design: reads are capped and CPU sampling is ≤ 2 s.

• Content returned by tools is data, not instructions. Clients should present it to models accordingly.

Configuration

All settings are environment variables, validated at startup. Invalid values stop the server rather than being silently replaced.

Operations

Local development

Prerequisites: uv and, optionally, direnv. The .envrc keeps every cache, the virtualenv and temporary files under ./.cache/, and configures the git hooks and identity.

direnv allow                 # once; or export the variables from .envrc manually
uv sync --locked             # Python 3.12 + locked dependencies into .cache/venv

ruff check . && ruff format --check .
mypy src/ tests/ --strict
bandit -c pyproject.toml -r src/
pytest                       # sockets disabled, branch coverage, >= 95% floor
scripts/coverage-gate.sh     # 100% branch coverage on tools/sql.py, tools/fs.py, guardrails/

The test suite is hermetic. pytest-socket blocks all IP sockets for the whole run (Unix sockets stay available for the event loop), no test needs a live database, and MCP_* variables are cleared around each test. The suite covers:

• Unit: contracts and controls.

• Property-based: Hypothesis fuzzing, tests/unit/test_fuzz.py.

• End-to-end: the real server as a subprocess under python -X dev, tests/e2e/. These cover handshakes, concurrency, malformed input, oversized frames, signals and file-descriptor/task leak checks.

HYPOTHESIS_PROFILE=ci pytest tests/unit/test_fuzz.py --no-cov   # 1000 derandomised examples per property
pytest -m e2e --no-cov                                           # subprocess protocol tests only

Mutation checks. The repository ships no mutation-testing script or framework, so mutation checks are run by hand. Disable one defence, run its test module, confirm it fails, then restore the file. For example:

# Drop O_NOFOLLOW from the directory walk: test_fs_tool.py must fail.
sed -i.bak 's/os.O_DIRECTORY | os.O_NOFOLLOW/os.O_DIRECTORY/' src/mcp_server_suite/tools/fs.py
pytest tests/unit/test_fs_tool.py --no-cov; mv src/mcp_server_suite/tools/fs.py.bak src/mcp_server_suite/tools/fs.py

# Skip the LIMIT rewrite: test_sql_tool.py must fail.
sed -i.bak 's/root.limit(effective, copy=False).sql/root.sql/' src/mcp_server_suite/tools/sql.py
pytest tests/unit/test_sql_tool.py --no-cov; mv src/mcp_server_suite/tools/sql.py.bak src/mcp_server_suite/tools/sql.py

git diff --exit-code src/    # confirm the tree is restored

Container deployment

The image is a two-stage build:

• Builder: python:3.12-slim with uv installs the locked dependencies and the package into /opt/venv.

• Runtime: the same digest-pinned base, with no pip, uv, compilers or package managers. It runs as 10001:10001 with STOPSIGNAL SIGTERM.

docker build -t mcp-server-suite:local .

docker run --rm -i \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --network none \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=16m \
  --pids-limit 64 --memory 256m --cpus 1 \
  -v "$PWD/data:/safe_data_dir:ro" \
  mcp-server-suite:local

• Mount only the directory the model should read, read-only. Files must be readable by UID 10001 (world-readable files in a world-traversable directory are enough).

• Keep -i and omit -t: a TTY would rewrite the newline-delimited stream.

• To use read_only_sql, replace --network none with a network that reaches only the database, and pass -e MCP_SQL_DSN. Prefer an env file or secret store to putting the DSN on the command line.

docker-compose.yml applies the same profile, with resource reservations and a dedicated read-only safe-data volume:

docker compose build
docker compose run --rm -T mcp-server < requests.jsonl

scripts/smoke-docker.sh builds the image and checks the result:

• the UID is 10001;

• the root filesystem and /opt/venv reject writes while /tmp accepts them;

• pip, package managers and setuid binaries are absent;

• an MCP handshake over container stdio succeeds through both docker run and Compose;

• docker stop exits cleanly.

--offline validates the Dockerfile and Compose file without a daemon.

An MCP client launches the container like any stdio server:

{
  "mcpServers": {
    "mcp-server-suite": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--read-only", "--cap-drop", "ALL",
        "--security-opt", "no-new-privileges:true", "--network", "none",
        "--tmpfs", "/tmp:rw,noexec,nosuid,nodev,size=16m",
        "-v", "mcp-safe-data:/safe_data_dir:ro",
        "mcp-server-suite:local"
      ]
    }
  }
}

PostgreSQL least-privilege role

The AST policy and read-only transactions reduce risk. The role is what actually bounds it. Create a dedicated login role that can only read the objects you intend to expose:

-- Dedicated login role: no inheritance, no special attributes.
CREATE ROLE mcp_reader LOGIN NOINHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE
  NOREPLICATION NOBYPASSRLS CONNECTION LIMIT 8;
\password mcp_reader

-- Server-side defaults that hold even if a client-side layer is bypassed.
ALTER ROLE mcp_reader SET default_transaction_read_only = on;
ALTER ROLE mcp_reader SET statement_timeout = '10s';
ALTER ROLE mcp_reader SET lock_timeout = '1s';
ALTER ROLE mcp_reader SET idle_in_transaction_session_timeout = '15s';

-- Read access to one schema only; ideally a schema of curated views.
GRANT CONNECT ON DATABASE app TO mcp_reader;
GRANT USAGE ON SCHEMA reporting TO mcp_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA reporting TO mcp_reader;
ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA reporting
  GRANT SELECT ON TABLES TO mcp_reader;

• Keep CONNECTION LIMIT at or above MCP_SQL_POOL_MAX_SIZE.

• Never grant membership in pg_read_all_data, pg_read_server_files, pg_execute_server_program or pg_signal_backend.

• Use row-level security or views to expose only the rows and columns the model needs.

• Connect with TLS (?sslmode=verify-full):

  export MCP_SQL_DSN='postgresql://mcp_reader@db.internal:5432/app?sslmode=verify-full'

Continuous integration

.github/workflows/ci.yml runs on pushes to main and on every pull request, with contents: read permissions. Every action is pinned to a commit SHA, with its version in a comment.

Repository layout

src/mcp_server_suite/
  __main__.py        entry point: logging to stderr, stdio session
  core/              framing, JSON-RPC parsing, dispatcher, tool registry, stdio transport
  guardrails/        argument sanitizer, concurrency limiter, execution deadline
  schemas/           strict Pydantic contracts and the RFC 9457 error taxonomy
  tools/             read_only_sql, sandbox_fs_read, system_metrics
tests/
  unit/              contracts, controls, fuzzing, hermeticity, hook/CI policy parity
  e2e/               real-process stdio protocol tests
scripts/             attribution, hygiene, coverage and container smoke gates
.githooks/           pre-commit, commit-msg, pre-push (shared rules in _policy.sh)
Dockerfile, docker-compose.yml, .github/workflows/ci.yml

Contributing

• Commits use Conventional Commits (type(scope): subject) with no generated trailers.

• Author and committer must match the configured maintainer identity. The hooks in .githooks/ enforce this locally (git config core.hooksPath .githooks, set automatically by .envrc) and CI enforces the same rules.

• Integrate changes with a fast-forward or rebase and push. Merging through the GitHub web UI records GitHub as the committer, which the audit rejects.

• Keep caches and temporary files under ./.cache/. Never commit absolute machine paths; the hygiene gates reject them.

License

Released under the MIT License (SPDX: MIT). Copyright (c) 2026 mikeZ98.