This release is a pre-release and may not be stable for production use.
Kymograph
AKRENON Kymograph (mcp-kymograph) is a dynamic security testing tool for
Model Context Protocol servers. I wrote it to see what an
MCP server really sends, not what its description says it sends.
Formerly published as mcp-polygraph.
This is an alpha version. The commands work and are tested. Output formats can still change between versions.
What it does
- It records the message exchange between an MCP client and an MCP server, in both directions,
into one file per run (
events.jsonl). - It reports named signals: text in a tool description or a tool result that a model could read as an instruction.
- With a scenario file it can alter messages in flight, so that the reaction of the other side is in the recording too.
- It can run a server in a sandbox without a network and record every attempt to reach one.
- It masks credentials at the moment an event is written.
- It has a read-only web interface on
127.0.0.1for looking at recordings.
Kymograph is placed where you configure it. It starts the server as a child process over stdio, or it connects to a Streamable HTTP endpoint that you name. It does not intercept traffic of third parties.
What it does not do
- It gives no severities. A finding says that a pattern matched at a place in the recording.
- It gives no grades. It does not rate a server as safe or unsafe.
- It makes no statement about individual clients. Whether a text has an effect depends on the client and the model that read it, and the wire does not show that.
- A run without findings does not mean a harmless server. Most signals are heuristics. Honest text can match them, and other wording can pass them.
- It does not decide what you may test. Use it against servers you operate, against the fixture servers in this repository, or against systems for which you hold a written engagement.
Install
Requirements: Linux and Python 3.12 or later. At run time the tool needs only the standard
library. Reading YAML files needs the optional extra yaml (PyYAML).
With pip, from the package index:
python3 -m venv .venv
. .venv/bin/activate
pip install 'mcp-kymograph[yaml]'
kymograph --version
This installs the tool only. The quick start below uses files from this repository, so it needs a clone.
Or install from a clone. With uv:
git clone https://github.com/akrenon/mcp-kymograph.git
cd mcp-kymograph
uv sync
uv run kymograph --version
From a clone with pip:
git clone https://github.com/akrenon/mcp-kymograph.git
cd mcp-kymograph
python3 -m venv .venv
. .venv/bin/activate
pip install '.[yaml]'
kymograph --version
The command is kymograph. The same program is also installed as mcp-kymograph.
The commands below are written as with the environment active. With uv, activate it
(. .venv/bin/activate) or put uv run in front of each command.
Quick start
The folder examples/unmarked-result holds a small server and
four input files. The server has one tool, read_file. Its result is a note with a hidden
HTML comment that holds an instruction, and a canary value.
Run this from the root of the clone:
kymograph drive \
--script examples/unmarked-result/c_read-file.yaml \
--scenario examples/unmarked-result/c_result-observe.yaml \
--out-dir runs \
-- python examples/unmarked-result/marking_server.py \
--file examples/unmarked-result/c_note.txt --kind unmarked
Kymograph starts the server, speaks the client half from the script, and stops. The terminal
shows each message and then a summary with three findings (hidden_comment,
instruction_override, concealment_directive). The recording is in a new folder under
runs/:
RUN=$(ls -d runs/2* | tail -n 1)
kymograph verdict "$RUN/events.jsonl"
kymograph engagement marking "$RUN" --canaries-file examples/unmarked-result/c_canaries.json
verdict prints the state of the run. engagement marking says where the canary arrived and
whether the server marked that text as foreign content. Here it reports unmarked. That is an
observation, not a severity.
The example needs no network and no Docker. A second run gives the same findings.
The two modes
kymograph run (proxy) |
kymograph drive (driver) |
|
|---|---|---|
| Who starts the tool | an MCP client, from its own configuration | you, at a terminal |
| Who is the client | that client, with the model behind it | Kymograph itself, from a fixed script |
| What the recording shows | one real session, as it happened | what the server offers when it is asked the same questions every time |
Proxy mode records a session. The client varies, so a session is not repeatable.
Driver mode makes an inventory. There is no foreign client and no model. The same script against the same server gives the same recording, apart from the run id and the time.
Both modes write the same format. docs/clients.md shows how to put the proxy into a client's configuration.
Limits of isolation
- By default the server runs on the host, as a child process with your user's rights, your files and your network. What it sends anywhere else is not observed. The terminal says so on every such run. Do not run code you do not trust this way.
- A server that is an entry of a corpus manifest can run under
--isolation runc(kymograph drive --manifest FILE --entry NAME --isolation runc). It then runs in a container without a route to any network, and every attempt to reach one is recorded. This needs Docker on Linux and two images. docs/reference.md says how to get them. - The runc sandbox shares the kernel of the host. It keeps a server off the network. It does not protect the kernel.
- There is no gVisor runtime.
--isolation runscis accepted and always refused. - For an endpoint that someone else runs, the tool sees only the traffic between itself and the endpoint.
More documentation
- docs/reference.md: the commands and their options, the exit codes, the file formats, and the full list of limits.
- docs/signals/README.md: what each signal reads.
- docs/engagements.md: working under a written engagement.
- docs/web.md: the web interface.
The name
A kymograph is an instrument that writes a motion down as a trace over time: it records, and it does not judge.
Security
See SECURITY.md for how to report a vulnerability.
License
Metadata
Release files for mcp-kymograph 0.2.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_kymograph-0.2.0a1.tar.gz | 2.4 MB | With provenance | Details for mcp_kymograph-0.2.0a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_kymograph-0.2.0a1-py3-none-any.whl | Python 3 | none | any | Details for mcp_kymograph-0.2.0a1-py3-none-any.whl |
Total release size: 3.2 MB
Release files / mcp_kymograph-0.2.0a1.tar.gz
| Download URL | mcp_kymograph-0.2.0a1.tar.gz |
|---|---|
| Size | 2.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
628efc70090d8de2a4599d738f790e6d46415be3e74361992f78560499862537
|
|
BLAKE2b-256 checksum How to use checksums |
56fbcfd78bbb99078d5eccfcf11b32b6c3e27ea8697efc5d9af5eac988b7bf4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / mcp_kymograph-0.2.0a1-py3-none-any.whl
| Download URL | mcp_kymograph-0.2.0a1-py3-none-any.whl |
|---|---|
| Size | 827.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
03aa0d9953770f2b9d6d8271dd7d50c914529b892d68681b38132286db706e90
|
|
BLAKE2b-256 checksum How to use checksums |
24fd3f2457f03f0a1da38ce53de9001b574624a851c160e0ad6c86ac2df4a919
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for mcp-kymograph 0.2.0a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mcp_kymograph-0.2.0a1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.