From 1c37ea56d668f9ddee9e76e1f9f67b04841cd2b9 Mon Sep 17 00:00:00 2001 From: AgentStatus Date: Sun, 30 Aug 2026 19:09:19 -0700 Subject: [PATCH 1/4] Docs: optional TOA verify after conformance in CI Adjacent delivery-evidence check only. Not a protocol scenario. --- README.md | 20 ++++++++++++++++++ SDK_INTEGRATION.md | 22 +++++++++++++++++++ examples/toa-after-conformance.yml | 34 ++++++++++++++++++++++++++++++ 3 files changed, 76 insertions(+) create mode 100644 examples/toa-after-conformance.yml diff --git a/README.md b/README.md index d5c4cb3f..5ba9a893 100644 --- a/README.md +++ b/README.md @@ -305,6 +305,26 @@ steps: | `verbose` | No | Show verbose output (default: false) | | `node-version` | No | Node.js version (default: 20) | +### Optional: Tool Outcome Attestation (TOA) after conformance + +Protocol conformance and tool-delivery evidence are different checks. This framework does not grade tool outcomes. If your SDK CI already has a signed [toa](https://github.com/Carmel-Labs-Inc/toa) JSON (`toa/0.1`), you can optionally fail the job when offline verify fails. TOA is not a conformance scenario. No AgentStatus account is required to verify. + +```yaml + - uses: modelcontextprotocol/conformance@v0.1.11 + with: + mode: server + url: http://localhost:3001/mcp + + # Optional. Provide toa.json from your emit step or an artifact. + - name: Verify tool delivery attestation + if: hashFiles('toa.json') != '' + run: | + pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@345f24607919b5bdf143719b9ea062543cdfe88e#subdirectory=python" + toa-verify toa.json --require-layer functional=pass +``` + +See [`examples/toa-after-conformance.yml`](./examples/toa-after-conformance.yml). Pin the emitter public key with the flags documented in the toa repo when you need a specific signer. + ## Example Clients - `examples/clients/typescript/everything-client.ts` - Single client that handles all scenarios based on scenario name (recommended) diff --git a/SDK_INTEGRATION.md b/SDK_INTEGRATION.md index a0921150..65591b76 100644 --- a/SDK_INTEGRATION.md +++ b/SDK_INTEGRATION.md @@ -170,6 +170,28 @@ jobs: --- +## Optional: Tool Outcome Attestation (TOA) after conformance + +Conformance checks the wire protocol. [TOA](https://github.com/Carmel-Labs-Inc/toa) (`toa/0.1`) is separate signed JSON for tool delivery evidence (reach, invoke, functional, shape, and related layers). It is not a wire protocol and is not meant for every live `tools/call`. + +If your CI produces a `toa.json` from any emitter, you can optionally verify it after the conformance action. Off by default. No AgentStatus account is required to verify. + +```yaml + - uses: modelcontextprotocol/conformance@v0.1.10 + with: + mode: server + url: http://localhost:3001/mcp + suite: active + + - name: Verify tool delivery attestation + if: hashFiles('toa.json') != '' + run: | + pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@345f24607919b5bdf143719b9ea062543cdfe88e#subdirectory=python" + toa-verify toa.json --require-layer functional=pass +``` + +Full copy-paste example: [`examples/toa-after-conformance.yml`](./examples/toa-after-conformance.yml). + ## Writing Conformance Clients/Servers ### Example Client Pattern diff --git a/examples/toa-after-conformance.yml b/examples/toa-after-conformance.yml new file mode 100644 index 00000000..84fb639f --- /dev/null +++ b/examples/toa-after-conformance.yml @@ -0,0 +1,34 @@ +# Example only. Copy into an SDK or server repo as needed. +# Protocol conformance, then optional TOA verify (delivery evidence). +# TOA is not a conformance scenario. +name: MCP Conformance and optional TOA + +on: + pull_request: + branches: [main] + +jobs: + conformance-and-toa: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up and start server + run: | + # Replace with your SDK / server start. + echo "start your MCP server here" + # my-server --port 3001 & + # timeout 15 bash -c 'until curl -s http://localhost:3001/mcp; do sleep 0.5; done' + + - uses: modelcontextprotocol/conformance@v0.1.11 + with: + mode: server + url: http://localhost:3001/mcp + # expected-failures: ./conformance-baseline.yml + + # Optional: only runs when toa.json is present in the workspace. + - name: Verify tool delivery attestation + if: hashFiles('toa.json') != '' + run: | + pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@345f24607919b5bdf143719b9ea062543cdfe88e#subdirectory=python" + toa-verify toa.json --require-layer functional=pass From 124c05104ae1dc68ec7ddc47757507a337b58b0f Mon Sep 17 00:00:00 2001 From: AgentStatus Date: Sun, 30 Aug 2026 20:25:00 -0700 Subject: [PATCH 2/4] Docs: pin emitter and max-age on toa-verify examples Match toa-verify --require-emitter / --max-age 7d after Carmel-Labs-Inc/toa#1. --- README.md | 6 +++--- SDK_INTEGRATION.md | 4 ++-- examples/toa-after-conformance.yml | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5ba9a893..b332fdb1 100644 --- a/README.md +++ b/README.md @@ -319,11 +319,11 @@ Protocol conformance and tool-delivery evidence are different checks. This frame - name: Verify tool delivery attestation if: hashFiles('toa.json') != '' run: | - pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@345f24607919b5bdf143719b9ea062543cdfe88e#subdirectory=python" - toa-verify toa.json --require-layer functional=pass + pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@5a1bf1cf6a15a4864ea809fe7b2a073f2cef4e22#subdirectory=python" + toa-verify toa.json --require-emitter agentstatus --require-layer functional=pass --max-age 7d ``` -See [`examples/toa-after-conformance.yml`](./examples/toa-after-conformance.yml). Pin the emitter public key with the flags documented in the toa repo when you need a specific signer. +See [`examples/toa-after-conformance.yml`](./examples/toa-after-conformance.yml). Always pass `--require-emitter` (and `--max-age` when you need freshness). See the toa repo for `--public-key`. ## Example Clients diff --git a/SDK_INTEGRATION.md b/SDK_INTEGRATION.md index 65591b76..3b09ea46 100644 --- a/SDK_INTEGRATION.md +++ b/SDK_INTEGRATION.md @@ -186,8 +186,8 @@ If your CI produces a `toa.json` from any emitter, you can optionally verify it - name: Verify tool delivery attestation if: hashFiles('toa.json') != '' run: | - pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@345f24607919b5bdf143719b9ea062543cdfe88e#subdirectory=python" - toa-verify toa.json --require-layer functional=pass + pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@5a1bf1cf6a15a4864ea809fe7b2a073f2cef4e22#subdirectory=python" + toa-verify toa.json --require-emitter agentstatus --require-layer functional=pass --max-age 7d ``` Full copy-paste example: [`examples/toa-after-conformance.yml`](./examples/toa-after-conformance.yml). diff --git a/examples/toa-after-conformance.yml b/examples/toa-after-conformance.yml index 84fb639f..a7006e64 100644 --- a/examples/toa-after-conformance.yml +++ b/examples/toa-after-conformance.yml @@ -30,5 +30,5 @@ jobs: - name: Verify tool delivery attestation if: hashFiles('toa.json') != '' run: | - pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@345f24607919b5bdf143719b9ea062543cdfe88e#subdirectory=python" - toa-verify toa.json --require-layer functional=pass + pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@5a1bf1cf6a15a4864ea809fe7b2a073f2cef4e22#subdirectory=python" + toa-verify toa.json --require-emitter agentstatus --require-layer functional=pass --max-age 7d From cb085b9e7148b2070a19bc5daa80f179952c8b56 Mon Sep 17 00:00:00 2001 From: AgentStatus Date: Sun, 30 Aug 2026 20:29:19 -0700 Subject: [PATCH 3/4] Docs: pin toa-verify to packaged-key release Carmel-Labs-Inc/toa@99e2690fec24a5290d9542e58383a8bf753e8b74 ships keys/agentstatus-v1.json inside the python package (toa#2). --- README.md | 2 +- SDK_INTEGRATION.md | 2 +- examples/toa-after-conformance.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b332fdb1..3f36958f 100644 --- a/README.md +++ b/README.md @@ -319,7 +319,7 @@ Protocol conformance and tool-delivery evidence are different checks. This frame - name: Verify tool delivery attestation if: hashFiles('toa.json') != '' run: | - pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@5a1bf1cf6a15a4864ea809fe7b2a073f2cef4e22#subdirectory=python" + pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@99e2690fec24a5290d9542e58383a8bf753e8b74#subdirectory=python" toa-verify toa.json --require-emitter agentstatus --require-layer functional=pass --max-age 7d ``` diff --git a/SDK_INTEGRATION.md b/SDK_INTEGRATION.md index 3b09ea46..4500b983 100644 --- a/SDK_INTEGRATION.md +++ b/SDK_INTEGRATION.md @@ -186,7 +186,7 @@ If your CI produces a `toa.json` from any emitter, you can optionally verify it - name: Verify tool delivery attestation if: hashFiles('toa.json') != '' run: | - pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@5a1bf1cf6a15a4864ea809fe7b2a073f2cef4e22#subdirectory=python" + pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@99e2690fec24a5290d9542e58383a8bf753e8b74#subdirectory=python" toa-verify toa.json --require-emitter agentstatus --require-layer functional=pass --max-age 7d ``` diff --git a/examples/toa-after-conformance.yml b/examples/toa-after-conformance.yml index a7006e64..e89bf203 100644 --- a/examples/toa-after-conformance.yml +++ b/examples/toa-after-conformance.yml @@ -30,5 +30,5 @@ jobs: - name: Verify tool delivery attestation if: hashFiles('toa.json') != '' run: | - pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@5a1bf1cf6a15a4864ea809fe7b2a073f2cef4e22#subdirectory=python" + pip install "git+https://github.com/Carmel-Labs-Inc/toa.git@99e2690fec24a5290d9542e58383a8bf753e8b74#subdirectory=python" toa-verify toa.json --require-emitter agentstatus --require-layer functional=pass --max-age 7d From 5e2c0c6b33957a2390b0b67632adb4fec02452ec Mon Sep 17 00:00:00 2001 From: AgentStatus Date: Sun, 30 Aug 2026 20:38:38 -0700 Subject: [PATCH 4/4] Docs: align TOA emitter prose with --require-emitter example Match the sample command, which requires emitter.name=agentstatus and the packaged key. Co-authored-by: Cursor --- SDK_INTEGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SDK_INTEGRATION.md b/SDK_INTEGRATION.md index 4500b983..8916ab6d 100644 --- a/SDK_INTEGRATION.md +++ b/SDK_INTEGRATION.md @@ -174,7 +174,7 @@ jobs: Conformance checks the wire protocol. [TOA](https://github.com/Carmel-Labs-Inc/toa) (`toa/0.1`) is separate signed JSON for tool delivery evidence (reach, invoke, functional, shape, and related layers). It is not a wire protocol and is not meant for every live `tools/call`. -If your CI produces a `toa.json` from any emitter, you can optionally verify it after the conformance action. Off by default. No AgentStatus account is required to verify. +If your CI produces a `toa.json` from AgentStatus (or another emitter whose key you pin), you can optionally verify it after the conformance action. Off by default. The example below requires `emitter.name=agentstatus` and uses the packaged AgentStatus key; pass `--public-key` for another issuer. No AgentStatus account is required to verify. ```yaml - uses: modelcontextprotocol/conformance@v0.1.10