Stripe pack: recorder and OpenTelemetry setup
Running the MCP recorder with the Stripe pack's mapping, changing the mapping, the warning for tools without a rule, and what OpenTelemetry ingestion adds.
Last changed Markdown versionllms.txt
How an agent's tool calls become recorded actions of the Stripe Customer Operations pack without code of your own, and what OpenTelemetry adds. Both sections are the pack's own templates, included from its files. The recorder's full reference is on the Python and TypeScript recorder pages; the span convention is on the OpenTelemetry convention page.
MCP: record from the tool call itself
The MCP recorder is a stdio proxy between the agent and one MCP server. It forwards every message unchanged and
records each mapped tools/call as an action before forwarding it. It reads the request's arguments, never the
tool server's credentials or its answer.
pip install commitlayer-mcp-recorder
export COMMITLAYER_API_KEY="paste-your-recorder-key"
curl -sS "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/recorder-mapping" \
-H "X-API-Key: $COMMITLAYER_API_KEY" > recorder.json
commitlayer-mcp-recorder --map recorder.json --warn-unmapped -- your-mcp-server --its-arguments
Replace your-mcp-server --its-arguments with the command that starts your MCP server over stdio. The same
command line works for the TypeScript build (npm install -g @commitlayer/mcp-recorder). The key is a recorder
key (Settings, API keys); it can read the mapping and cannot push facts. The mapping is your workspace's own copy
with contract_version pinned to the drafts the install created, so fetch it after installing the pack and
activating its contracts: an action recorded against a draft nobody selected is refused (409 contract_not_active). The file
holds only the keys a recorder reads.
What the mapping records
| Tool key | Contract | Subject | Action id |
|---|---|---|---|
stripe.refund |
scop_refund_order |
arguments.order_id |
refund:{order_id} |
stripe.refunds_create |
scop_refund_order |
arguments.metadata.order_id |
refund:{order_id} |
shopify.refund_order, shopify.cancel_order |
scop_refund_order |
arguments.order_id |
refund:{order_id} (the cancel and the refund are one action) |
stripe.subscriptions_cancel |
scop_cancel_subscription |
arguments.subscription |
cancel:{subscription} |
stripe.credit_notes_create |
scop_issue_credit_note |
arguments.invoice |
credit:{invoice} |
stripe.invoices_adjust, stripe.invoices_void |
scop_adjust_invoice |
arguments.invoice |
adjust:{invoice} |
zendesk.update_ticket, or intercom.close_conversation, salesforce.update_case, hubspot.update_ticket |
scop_resolve_customer_case |
zendesk_ticket_{ticket_id}, intercom_conv_{conversation_id}, sf_case_{case_id}, hubspot_ticket_{ticket_id} |
resolve:{subject} |
The tool keys and argument names are this pack's convention. They are not a verified list of any vendor's MCP
tool names: compare them with the tools/list answer of the server you run, and change the mapping where they
differ (below). The recorder matches the exact key first, then the first key whose part after the last dot is the
tool's name, so subscriptions_cancel on your server is matched by stripe.subscriptions_cancel.
Things to know before the first call:
- Amounts.
stripe.refunds_createandstripe.credit_notes_createare declaredunits: {amount: minor}: the tool sends4000for forty dollars, as the Stripe API does, and the intake records40.0and keeps what was sent underaction.units. Every other tool key is read as sent, in major units. If your tool sends cents under another key, add"units": {"amount": "minor"}to its rule in the annotated document (below). The conversion goes by the call'scurrency: divided by 100, and taken as sent for the currencies Stripe's currency page lists as zero-decimal (JPY and KRW among them). A call that states no currency is read as hundredths, andaction.unitssays so (currency: null, decimals: 2); this pack's keys for Stripe's own refund and credit-note calls readarguments.currency, and whether your server's tool carries one is yours to check. Three-decimal currencies are read as hundredths. - One action, said twice. A retry, or the second mapped tool for the same order, renders the same action id
and is the same action when it agrees with the first record on every parameter both carry; the first record
stands. The reason is left out of that comparison (
describeson the rule). Another amount, customer, payment or support case under the same id is refused with409 conflict, and so is a later call that states a parameter a check reads when the first did not: a cancellation recorded withoutrefund_amount, then a refund with an amount, is two statements the first record cannot hold, and the action stays UNKNOWN on policy. - Arguments the checks read. A refund must carry
amount; a cancellation must carrycancel_at_period_end(trueorfalse); a case resolution must carryresolution_kind. A call without one is recorded, and its action is UNKNOWN on the policy lens (param_missing:<name>) where it would have passed. If your tool has no such argument, record the action from your own code instead (the REST or SDK example), where you can state it. - Order id. The refund tools need the order id in the call (
order_id, ormetadata.order_idforstripe.refunds_create). A call without it is forwarded and not recorded; the recorder logs the missing path. - One action per order, subscription, invoice or case. A retried call, or a second mapped tool for the same
order (a cancel after a refund), renders the same action id and is the same action: the first record stands. A
call that gives another amount for the same id is refused with
409 conflictand logged; the call itself is still forwarded unless you run with--no-fail-open. - Your help desk only. The served mapping holds the rule of the help desk your
resolve_customer_casecontract reads (Zendesk by default), not the other three. - Help-desk subjects need a newer recorder. The help-desk rules build the subject from a template
(
zendesk_ticket_{arguments.ticket_id}). The published recorders (commitlayer-mcp-recorder0.1.1 on PyPI,@commitlayer/mcp-recorder0.1.2 on npm) read a subject as a plain path, forward those calls unrecorded and log the unresolved path; subject templates are in the client repository from recorder 0.1.3 (Python) and 0.1.4 (TypeScript), which are not published yet. The Stripe and Shopify rules record with the published versions. - A general update tool. A rule fires on every call of its tool.
zendesk.update_ticket,salesforce.update_caseandhubspot.update_ticketare recorded as a resolution whenever they are called, whatever the update was. If your agent uses the tool for other updates, remove the rule and record the resolution from your own code.
Change or extend the mapping
The mapping is yours to edit. The file a recorder reads holds the recorder's own keys only, so edit the annotated
document instead: it is the same mapping with the keys only the API reads (units, when_source and describes in a rule,
consequential_tools, read_only_tools and customised_at at the top).
export COMMITLAYER_FULL_KEY="paste-your-full-key" # a key with the full preset (Settings, API keys)
curl -sS "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/recorder-mapping?annotated=true" \
-H "X-API-Key: $COMMITLAYER_FULL_KEY" > mapping.json
In mapping.json, rename a key to the name your server gives the tool, change a path to your tool's argument, add
a rule for another tool, list your own consequential_tools. Then store it and fetch the recorder's file again:
curl -sS -X PUT "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/recorder-mapping" \
-H "X-API-Key: $COMMITLAYER_FULL_KEY" -H "Content-Type: application/json" \
-d "{\"mapping\": $(cat mapping.json)}"
curl -sS "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/recorder-mapping" \
-H "X-API-Key: $COMMITLAYER_API_KEY" > recorder.json
Storing needs a key with every scope (the full preset): a recorder key is refused with 403, because the
mapping decides which calls are recorded at all. A rule that leaves out units, when_source or describes
keeps what the stored rule of the same tool name has, so recorder.json sent back does not take the unit off an
amount; send a key empty ("units": {}) to remove it. A tool you rename has no stored rule: state its units
again, or its amount is read in major units from then on. A rule must name a contract_id that is an action contract of your workspace and a subject; a rule for one
of the pack's contracts without contract_version is pinned to the installed draft. The stored copy is kept
through an upgrade and a rollback; only the help desk's rule changes with helpdesk_source. Do not give mapping.json to a recorder: the TypeScript recorder refuses a
file with a key it does not know. There is no editor for the mapping in the app yet; the pack's Recorder mapping
tab shows it read-only.
The warning for tools without a rule
--warn-unmapped logs, once per tool name, every call the recorder forwarded without a rule. It is off unless
you pass it, and it cannot tell a refund from a read. To make the warning visible to the workspace, report the
tool names your server exposes, with the server's own read-only flag where it has one:
curl -sS -X POST "https://api.commitlayer.ai/v1/packs/stripe_customer_operations/observed-tools" \
-H "X-API-Key: $COMMITLAYER_API_KEY" -H "Content-Type: application/json" \
-d '{"tools": [{"name": "stripe.payouts_create"}, {"name": "stripe.invoices_list", "read_only": true}]}'
GET /v1/packs/stripe_customer_operations/coverage then lists under unmapped_consequential_tools every
reported tool that has no rule and was not read-only when first reported, together with every tool in the mapping's
consequential_tools that has no rule; the pack's Coverage page in the app shows the same list. The recorder does
not send this report itself yet, so a tool nobody listed and nobody reported is not known to CommitLayer.
The read-only flag counts the first time a name is reported. A tool once reported as changing something stays
so through this route, because it accepts the recorder's key and that key must not be able to quieten the
warning. If a read was reported without the flag, list it under read_only_tools at the top of mapping.json
and store the mapping (above); coverage then stops warning for it.
The CommitLayer MCP server
Separate from the recorder: the CommitLayer MCP server gives an assistant read access to packs. Its pack tools
are list_workflow_packs, get_workflow_pack, get_pack_requirements, validate_pack_configuration,
dry_run_workflow_pack, draft_pack_contract, compare_pack_versions, get_pack_coverage and
get_pack_scenarios. None of them installs, activates, weakens a contract or pushes a fact; a person activates
in the app or with POST /v1/contracts/{id}/select.
OpenTelemetry: runtime context beside the verdict, not a way to record a pack action
OpenTelemetry ingestion does not record an action under a pack contract today. Record the action with the REST API, an SDK or the MCP recorder. What the ingestion does with an agent's spans is narrower:
- A span that carries
agent.action.typeandagent.action.subject_idbecomes a fact with sourceotel, classedruntime_context. It ranks asself_reportedwhatever trust is declared, and no check of this pack reads theotelsource, so it never satisfies an expected effect. It does count as a fact on the subject: an action that would have read UNKNOWNidentity_unmatched, because nothing was known about its subject, is judged on its expected effects instead and reads FAIL while they are missing. It appears in the fact list of an action on the same subject, as context for the person reading the verdict. - A span that carries
agent.outcome.typeandagent.outcome.subject_idbecomes a claim under theinternal_agent_otelcontract (an outcome claim for statements), not a pack action. - Every other attribute is dropped at ingestion. The convention is in
docs/otel-convention.md.
Setup
A signed-in admin creates the source in the app (Internal agents); the route behind it, POST /v1/otel/sources,
does not accept an API key. The answer shows the endpoint once, with its key in the URL. The endpoint accepts OTLP/HTTP JSON only: a protobuf body is answered
415, so set your exporter or collector to http/json.
export COMMITLAYER_API="https://api.commitlayer.ai"
export OTEL_ENDPOINT_KEY="paste-the-endpoint-key"
curl -sS -X POST "$COMMITLAYER_API/v1/otel/$OTEL_ENDPOINT_KEY/v1/traces" \
-H "Content-Type: application/json" \
-d '{
"resourceSpans": [{
"scopeSpans": [{
"spans": [{
"traceId": "5b8aa5a2d2c872e8321cf37308d69df2",
"spanId": "051581bf3cb55c13",
"name": "stripe.credit_notes_create",
"startTimeUnixNano": "1794474120000000000",
"endTimeUnixNano": "1794474121000000000",
"attributes": [
{"key": "agent.action.type", "value": {"stringValue": "credit_note_requested"}},
{"key": "agent.action.subject_id", "value": {"stringValue": "in_1PxYz"}},
{"key": "agent.name", "value": {"stringValue": "billing-agent"}}
]
}]
}]
}]
}'
The answer is {"accepted": 1, "claims": 0, "facts": 1}: one span read, one agent_action fact on in_1PxYz.
Use the Stripe id of the subscription or invoice (or your order id) as agent.action.subject_id, so the fact
lands on the subject the action names.
What stays out of the span: the Stripe secret key, the customer's email or card, the response body. Only the attributes above are kept.