GxP Gateway Audit

mcp-name: io.github.antonio-castellon/mcp-glp-audit-proxy

mcp-glp-audit-proxy

GxP Gateway Audit (package mcp-glp-audit-proxy) audits MCP and HTTP(S) APIs, gateways, and LLM endpoints. Community edition, v0.4.0. The package name, the command names, and the MCP Registry id stay mcp-glp-audit-proxy. Changes since 0.2.0 are in CHANGELOG.md.

The listener and every remote URL are HTTPS with TLS 1.3. Plain HTTP is refused. With no listen object the process is still the stdio MCP proxy between a host and its MCP servers.

It is designed to support GLP / 21 CFR Part 11 / EU GMP Annex 11 workflows. Data stays on the customer's infrastructure. This package is the open core. Signed checkpoints, WORM storage, PDF/CSV reports, the IQ/OQ pack and SSO/OAuth are Pro features and are not in this repository. Personal Part 11 e-signatures are out of scope. Community is tamper-evident via the hash chain. It is not signed. Signing is Pro.

Install

Requires Python 3.11 or newer.

pip install mcp-glp-audit-proxy

From a checkout:

pip install -e ".[dev]"

The mcp dependency is pinned to >=2.2.0,<3. That floor is outside GHSA-84m7-p3x7-pcfv (affected ranges are mcp >=1.8.0,<1.30.0 and >=2.0.0,<2.2.0). The process refuses to start on an older SDK.

Run

export GLP_PRINCIPAL_ID=operator-1

export GLP_PRINCIPAL_NAME="Ada Analyst" export GLP_PRINCIPAL_ROLE=operator mcp-glp-audit-proxy --config config.json

Stdio identity comes from the environment (GLP_PRINCIPAL_ID, GLP_PRINCIPAL_NAME, GLP_PRINCIPAL_ROLE). When the config has no listen object, the process reads newline-delimited JSON-RPC on stdin and writes it on stdout, and it does not open a socket. When listen is set, the same command serves HTTPS and does not read stdio. A Cursor snippet is in mcp.json. A full config is in config.example.json. The config reference is docs/manual-guides/README.md.

plugins.storage, plugins.signer, plugins.reporters and plugins.auth select entry points. The defaults are jsonl, unsigned, json plus text, and env. env returns the principal from GLP_PRINCIPAL_* or the config file. It is not an identity provider. An unknown plugin, or a plugin whose declared licence feature is not enabled, refuses to start. The factory is not called. The proxy does not fall back to another backend. See docs/PLUGINS.md.

Verify a chain and write a searchable JSON export (the export is skipped when the chain does not verify):

mcp-glp-audit-proxy-verify data/audit.jsonl --json-export exports/audit.json

mcp-glp-audit-proxy-verify data/audit.jsonl --tool excel__write_cell --status ok mcp-glp-audit-proxy-verify data/audit.jsonl --print-head

--print-head prints seq= entry_hash=<64 hex>. Copy that line into a ticket, an email or a LIMS record. Check it later with --expect-head : or --expect-head-file (the file may hold that same line). The command exits 1 when the chain tip differs. The sidecar data/audit.jsonl.head makes a cut of whole trailing lines fail verification. Someone who can edit both the log and the sidecar can move them together; the external copy is the control. Community is tamper-evident via the hash chain. It is not signed. Signing is Pro. --pubkey passes a pinned public key file to the licensed signer plugin. With no licensed signer the check fails. Pass --licence and --client-id, or set GLP_LICENCE_PATH and GLP_CLIENT_ID, to load that signer. With no licence path, no licence file is read. A missing or invalid licence exits 2. Unsigned checkpoints stay the default and are not treated as signed. The log and the .head sidecar are mode 0600 on open. A log directory created by the store is mode 0700.

Configure

init asks for the audit log path, the tool allow list, the principal (id, name, role), and the retention profile and legal hold. It writes a JSON config the same loader as startup accepts, with mode 0600. Prompts and the file are ASCII. The wizard does not open a network connection. If the destination already exists, it is left unchanged unless you answer yes to the overwrite question.

mcp-glp-audit-proxy init

mcp-glp-audit-proxy init /srv/glp/config.json

The default path is GLP_CONFIG when that variable is set, otherwise config.json. That is the same file the proxy reads.

config check loads a config and prints a plain-language error when it does not load. The process exits 0 when the file loads and 1 when it does not. It uses the same loader as startup, including the GLP_* overrides. The default path matches init.

mcp-glp-audit-proxy config check

mcp-glp-audit-proxy config check config.json

A licensed plugin can add questions and a validation step through the mcp_glp_audit_proxy.wizard entry point. An unlicensed plugin is not called and adds nothing. See docs/PLUGINS.md.

A licence file is local. There is no network call. LM1 is three lines: LM1, base64 of the body, and base64 of an RSA-2048 PSS signature over those raw bytes. LM2 is three lines: LM2, base64 of the body, and base64 of a 64-byte Ed25519 signature over those raw bytes, and the body must be compact sorted JSON. LM1, and LM2 with no features list, enable the features declared by the installed licensed plugins. An LM2 file that lists features enables only the listed names. Any other file is rejected. The production public keys are in release_trust.json and are loaded by trusted_keys() in mcp_glp_audit_proxy.trust. The fingerprint is not a machine id. Details are in docs/PLUGINS.md.

What is recorded

Every mediated call, including denials and failures, is one JSON object on an append-only JSONL file. Each line is RFC 8785 canonical JSON. entry_hash is the SHA-256 of that object with entry_hash removed. prev_hash is the previous entry (64 zero digits for the first). hash_algo and canonicalization are stored on the entry. The open schema is schema/audit-record.schema.json. Cross-language vectors are in schema/jcs-test-vectors.json.

Fields include who (principal id, name, role), which tool, inputs, outputs, UTC timestamp plus utc_offset, protocol version, optional session id, record class (gxp_data, access, technical, config), reason for writes, and the previous hash.

Schema 1.3.0 stores transport (stdio or https), channel (mcp or https), flow (mcp2mcp, mcp2api, api2mcp, api2api, mcp2llm, api2llm, or null on local records), http, arguments_sha256, and result_sha256. The http object holds the method, the route template, the path with the query string removed, the kept headers, the names of stripped credential headers, the body SHA-256, body_mode, the stored body, the status, latency_ms, and kind (api, llm, or mcp). The query string is forwarded and is not stored. 1.0.0 and 1.1.0 lines omit the later keys. 1.2.0 lines omit the two SHA-256 fields. Older lines stay valid in the same chain.

The GxP trail is that file. The Python logging logger mcp_glp_audit_proxy.technical writes method, status and record class to stderr. It is not the record. Arguments are not written there.

Policy

• Allow list and deny list use shell-style globs on the exposed tool name (excel__write_cell). Deny wins. An empty allow list denies every upstream tool.
• Roles are operator, approver, qa and admin. Only operator may call upstream tools. qa is read-only on the trail (glp_verify_chain, glp_search_audit, glp_export_audit). approver may record an approval and read the trail. admin may change policy and read the trail, and cannot call upstream tools.
• Auditing cannot be switched off. glp_update_policy with audit_enabled: false is denied and logged.
• Write tools (names matching write_tools) require a reason by default. The reason is _meta["io.github.antonio-castellon/reason"] or the argument _glp_reason (stripped before the upstream call).
• Optional human approval holds the write until a different person in the approver role records meaning approved. reviewed is stored with status reviewed and does not authorise the write. A log written before schema 1.1.0 may show that decision as status approved with meaning reviewed; those lines still verify and still do not authorise the write. rejected rejects it. An approval is single-use, bound to the SHA-256 of the canonical {tool, arguments}, and expires (default 3600 seconds). A successful write that presents a matching approval records it as consumed even if require_approval_for_writes was turned off before that call. A failed upstream call does not consume it. The record label is approval. It is not an electronic signature.
• HTTP routes use a second pair of lists, http_allow and http_deny. Each entry is METHOD /path with a shell-style glob on the path (GET /v1/studies/*). Deny wins. An empty http_allow denies every HTTPS route. It does not deny MCP tool calls. Only operator may call an HTTPS route.
• audit.body_mode is hash_only (the default for a new config), redacted, or full. Which value to use is the customer's and QA's decision. body_mode applies to HTTPS bodies and to MCP tool-call arguments and results. The SHA-256 of the raw request body is always recorded, and the SHA-256 of MCP tool arguments and results is recorded the same way. hash_only stores no body bytes and no MCP payload. redacted stores JSON with the paths in audit.redact_paths replaced by *** (a non-JSON body stores no plaintext). full stores the parsed JSON, or the UTF-8 text, of the request inside the hash-chained record, and full also stores the response text as response_body next to response_sha256. The log file is mode 0600. Binary that is not UTF-8 is hashed and not stored as the request body. The response body is returned to the client in every mode. A write request without Content-Length, or with Transfer-Encoding, is refused with 411 and logged. In hash_only and redacted modes the trail proves that a payload existed and was unaltered, but does not show its content; the content record must be kept by the target system (OECD N