> ## Documentation Index
> Fetch the complete documentation index at: https://subtext.fullstory.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Subtext Privacy MCP Tools: Complete Reference Guide
> Complete reference for Subtext's privacy MCP tools: privacy-propose, privacy-create, privacy-list, privacy-promote, and privacy-delete.
The five privacy tools form a complete governance loop: scan a session for PII, propose masking rules, persist them in preview scope, inspect what's active, promote approved rules to production, and clean up preview rules you no longer need. Each tool is designed to be called by your agent directly — no manual UI steps required.
## Safety model
Before diving into individual tools, it helps to understand the two-tier scope system that underpins all of them.
**Preview rules** exist to make iteration safe. When your agent creates a rule, it lands in preview scope first. Preview rules apply only to sessions opened in preview mode, leaving your production capture untouched. You can create, test, and delete preview rules freely.
**Live (production) rules** apply to every captured session. They are created by promoting a preview rule, and they cannot be deleted through the agent tooling.
The agent can only delete **preview** rules. Live rules are intentionally protected from deletion via the MCP tools — removing a production masking rule could expose PII in all future recordings. To remove a live rule, use the Subtext dashboard directly.
This asymmetry means your agent can autonomously handle the entire propose-create-promote cycle while a human retains final authority over what gets removed from production coverage. The tooling is designed to let the agent move fast without being able to accidentally dismantle your privacy posture.
***
### `privacy-propose`
Scan a session for PII and propose masking rules as a dry-run.
`privacy-propose` is a read-only operation. It inspects the session's event stream, identifies elements that appear to contain personally identifiable information, and returns a list of suggested CSS selectors along with a rationale for each match. Nothing is written to Subtext — no rules are created, no state changes.
**Key behaviors:**
* Returns candidate CSS selectors, not finalized rules. You decide which suggestions to act on.
* The agent evaluates visible text content, element attributes, and contextual signals (field labels, surrounding copy) to assess PII likelihood.
* Safe to call multiple times on the same session without side effects.
Run `privacy-propose` on a freshly captured session after shipping any feature that introduces new user-facing data. It's the fastest way to catch unmasked PII before it accumulates in your session archive.
**Example usage:**
```
privacy-propose(session_id="ses_abc123")
```
The agent returns something like:
```
Proposed masking rules for session ses_abc123:
1. Selector: [data-testid="account-email"]
Reason: Visible email address in account settings panel.
2. Selector: .profile-card__phone
Reason: Phone number rendered as plain text in user profile.
```
Pass the selectors you want to keep into `privacy-create` to persist them.
***
### `privacy-create`
Persist privacy rules from CSS selectors in preview scope.
`privacy-create` takes one or more CSS selectors and writes them as masking rules scoped to **preview sessions only**. Elements matching these selectors will be blocked in the session replay viewer when a session is opened in preview mode, giving you a way to verify correct behavior before rolling out broadly.
**Key behaviors:**
* Rules created here do **not** affect your production session capture until explicitly promoted.
* Returns a rule ID for each created rule — save these IDs to use with `privacy-promote` and `privacy-delete`.
* You can create rules from selectors you wrote yourself, not just those returned by `privacy-propose`.
Creating a preview rule does not modify any previously recorded sessions. It only affects sessions captured after the rule is created and viewed in preview mode.
**Example usage:**
```
privacy-create(selectors=["[data-testid=\"account-email\"]", ".profile-card__phone"])
```
Response:
```
Created 2 preview rule(s):
- rule_id: prv_001 selector: [data-testid="account-email"]
- rule_id: prv_002 selector: .profile-card__phone
```
***
### `privacy-list`
List all current element-block (privacy) rules.
`privacy-list` returns every active privacy rule across both preview and production scopes. Use it to audit your masking coverage, confirm that a newly created rule is registered, identify candidates for promotion, or spot rules that are redundant or outdated.
**Key behaviors:**
* Returns rules from both scopes in a single response.
* Each rule entry includes its ID, CSS selector, scope (preview or live), and creation timestamp.
* Read-only — calling this tool changes nothing.
**Example usage:**
```
privacy-list()
```
Response:
```
Active privacy rules:
Preview scope:
- prv_001 [data-testid="account-email"] created 2025-06-10
- prv_002 .profile-card__phone created 2025-06-10
Live scope:
- live_007 input[name="cc-number"] created 2025-04-02
- live_008 .checkout__cvv created 2025-04-02
```
***
### `privacy-promote`
Promote a preview rule to live scope so it applies to all sessions.
`privacy-promote` escalates a preview rule to production. After promotion, every new session your application captures will mask elements matching the promoted rule's selector. The rule also becomes protected — it can no longer be deleted through the agent tooling.
**Key behaviors:**
* Accepts a single rule ID per call. Promote rules one at a time so you can validate each one individually.
* Promotion is immediate — the rule goes live as soon as the call succeeds.
* The original preview rule is replaced by a new live rule with a different ID. Update any references accordingly.
* Past recordings are not retroactively affected; masking applies to sessions captured after promotion.
Promotion is a one-way operation via the agent tools. Once a rule is live, it cannot be demoted or deleted through `privacy-delete`. Review your selectors carefully in preview before promoting.
**Example usage:**
```
privacy-promote(rule_id="prv_001")
```
Response:
```
Rule prv_001 promoted to live scope.
New live rule ID: live_019
Selector: [data-testid="account-email"]
Applies to: all new sessions
```
***
### `privacy-delete`
Delete a preview rule by ID.
`privacy-delete` removes a preview rule permanently. Use it to discard selectors that turned out to be incorrect, overly broad, or no longer needed after a UI change. Only preview rules can be deleted through this tool — live rules are protected.
**Key behaviors:**
* Accepts a rule ID that must correspond to a preview-scoped rule. Passing a live rule ID returns an error.
* Deletion is immediate and irreversible for the rule record itself. You can always recreate a rule with the same selector if needed.
* Does not affect any previously captured sessions.
To remove a live rule, navigate to the Privacy section of the Subtext dashboard. This deliberate friction ensures that production masking coverage is never reduced without a conscious manual action.
**Example usage:**
```
privacy-delete(rule_id="prv_002")
```
Response:
```
Preview rule prv_002 deleted.
Selector .profile-card__phone will no longer be applied in preview sessions.
```
If you accidentally pass a live rule ID:
```
Error: rule live_007 is in live scope and cannot be deleted via the agent tools.
Use the Subtext dashboard to manage live rules.
```