MCP Workflows

Platform MCP works best when the client follows a read, plan, change, verify loop.

These examples show safe autonomous patterns. They use tool names, not a specific client UI, so you can adapt them to Claude, Cursor, OpenCode, or a custom client.

Workflow Guardrails

Before giving an MCP client write access:

1. Give it the smallest preset or exact permissions that fit the job.
2. Keep destructive permissions off by default.
3. Ask the client to produce a plan before write tools run.
4. Require human approval before destructive tools.
5. Verify changes with read tools after every write.
6. Review MCP Connections → Recent Audit Events after the run.

Audit An Agent Before Launch

Best permissions: Agent Builder plus sources:read, retrieval:read, feedback:read, and conversations:read.

Only after the plan is approved should the client use update_agent_prompt, update_agent_model, or update_agent_retrieval_settings.

For agents in the durable platform cohort, chat_playground, chat_with_agent, and test_agent return an additive turnId and terminal state. They wait for committed output, not an early model finish. cancel_agent_turn accepts { agentId, turnId } (agent keys may omit agentId) and explicitly stops that tenant/agent-bound turn. It requires chat:write, access to the agent and, for saved turns, the corresponding playground or conversation resource. Cancellation remains available after the cohort is disabled. Disconnecting a tool's HTTP request only detaches; a cancelled parent Copilot intentionally cancels the child turn it invoked. Known usage is still charged.

Add And Sync Knowledge Sources

Best permissions: Content Manager.

1. Use list_sources to avoid duplicates.
2. Use create_source for one URL, sitemap, file, or image source.
3. Use create_bulk_upload for a ZIP upload URL that already exists.
4. Use batch_sources for multiple FILE or IMAGE sources.
5. Use sync_source to queue ingestion or reindex.
6. Use list_ingestion_jobs or get_ingestion_job until the job succeeds or fails.
7. Use search_knowledge_base to verify retrieval.

Do not give sources:delete unless the workflow is allowed to remove sources. Source creation and sync only need sources:write.

Operate Conversations

Best permissions: Operator.

Use this when an internal assistant helps support teams triage active conversations.

1. list_conversations with status or channel filters.
2. get_conversation and list_conversation_messages to understand context.
3. get_end_user and get_end_user_memory to understand the customer.
4. takeover_conversation when a human should respond.
5. send_conversation_message for a human-authored text reply in a WEB_TEXT takeover conversation. Meta-channel replies use their channel-specific inbox flow.
6. assign_conversation or close_conversation when the support flow is complete.

Use set_end_user_memory only for facts the team wants saved for future conversations.

First-party channel-runtime calls recheck their recorded message/checkpoint sources before publishing a reply or replaying a saved result. Newly materialized first-party human and channel AI text/media replies retain those known inputs even after their creator execution retires. Attributed message-page reads and human-reply replays cannot treat the saved copy as an independent fact.

Latest-message previews returned by get_end_user, get_conversation, list_conversations and get_active_conversation also retain their message inputs for first-party channel-runtime calls. A preview whose known sources were deleted is rejected before returning content; a later write cannot reuse preview facts consumed before deletion. Conversations hidden by resource grants and pagination lookahead are not consumed.

The three conversation tools also retain known inputs for the visible customer name, email, phone and language they return. A grant-hidden customer, unreturned metadata or blocking reason is not consumed; changing the current profile does not erase inputs an earlier execution already read.

For first-party channel-runtime calls, the conversation returned by send_conversation_message follows the same visible-field and latest-message source rules. A rejected new reply rolls back its message, counters and audit; hidden customer fields and an old preview replaced by the new reply are not consumed.

The same rules apply to the conversation returned by takeover_conversation, release_conversation, assign_conversation and close_conversation, including retries. A revoked original input or returned fact prevents the state change, assignment-version increment and audit from committing. Existing permission and assignment requirements still apply.

Customer results from create_end_user and update_end_user retain known sources for their returned profile fields too. A revoked returned fact rolls back the mutation and audit. Independently supplied replacements remain possible. Content-free identity/block/unblock controls may return independent current values after an unrelated older read was revoked; those old inputs remain recorded and cannot be reused in a later content write.

SOURCE_CONTENT_REVOKED means an input was confirmed for deletion; do not retry those facts. Collect current facts in a fresh turn instead. Automatic channel history omits known-tainted replies so independent new turns remain available. This does not recall existing copies or certify exhaustive erasure across unrecorded readers or other destinations.

Copilot also rechecks known cleanup before exposing a saved customer action result. A pre-cleanup profile snapshot or approved memory ID can become unavailable with RESOURCE_DENIED even though the original mutation succeeded. Do not repeat that mutation to recover the old facts. Fresh independent results remain accessible. This does not certify physical erasure of Copilot history or exhaustive input lineage.

Native Copilot get_end_user_memory reads retain known channel-message and checkpoint inputs with their original run. Confirmed deletion makes those inputs unavailable, including delayed confirmed customer writes and their retry ancestry after the current memory value changes. Existing grants still apply; a run ID does not grant customer access. Use a fresh turn with independently supplied current facts. These receipts do not establish exhaustive lineage for other Copilot reads, history or outputs, and do not certify physical erasure.

Confirmed Copilot customer writes also retain those known inputs with the memory or profile values they publish. Removing the originating Copilot run, action or thread does not make the copied facts independent. Later first-party reads and delayed writes still reject a known-deleted input, even after the current value changes. An independently supplied replacement, including the same text, remains usable; this is source tracking, not text matching.

Native Copilot get_end_user and list_end_users also retain known inputs behind the profile fields and metadata they return. Customer details retain selected latest-message previews and their known copied-reply ancestry. Unreturned pagination lookahead and conversations hidden by grants are not consumed. An owned active run is required for attributed reads; it never replaces resource authorization.

Native Copilot get_conversation, list_conversations, get_active_conversation and list_conversation_messages retain known returned profile, preview and raw/copied-history inputs too. Only profile fields actually exposed by the conversation result are consumed; hidden profiles, unreturned metadata and pagination lookahead remain independent. A known-deleted input prevents exposure or a later confirmed customer write even after the current profile or preview changes. This does not certify lineage or physical erasure for conversation summaries, titles, tags, saved outputs or other cross-parent copies.

If a known input is confirmed for deletion before Copilot finishes, its terminal publication fails with a content-free RESOURCE_DENIED instead of retaining an answer or caller-supplied error containing those facts. Cancellation still takes precedence. Start a fresh turn with independently supplied current facts; identical text alone is not denied. This completion fence does not erase previously stored replay chunks or certify all persisted Copilot outputs.

Retained replay pages and reconnect also reject known-deleted inputs with RESOURCE_DENIED before exposing their chunks. This does not change a previously successful run into a failed run or repeat its operation. Its content-free run outcome and empty past-the-end replay tail remain readable. Earlier delivery and stored output bytes are not erased by this read fence.

Live answer text is delivered only after its coalesced event passes durable source admission. Pending or rejected admission does not expose that answer text. Existing flush settings still control batching; no new response-length limit is added. This does not recall text already admitted and delivered before a later deletion.

Published native answers retain a message-owned snapshot of their known channel inputs, independent of creator-run retirement. Private message pages, latest/full context and raw managed history omit copied answers whose known inputs were deleted. Pagination continues past suppressed rows, explicit latest limits still select available input, and independently supplied identical text remains readable. This prevents redisclosure; it does not erase retained private bytes or certify unrecorded historical copies and native shared compaction summaries.

Native model turns also retain known original inputs behind saved raw history they actually consume. The binding uses the original active owned run and thread; managed snapshots must match its participant and submitted message. Later deletion fences delayed customer writes, stream/terminal publication and new copied answers, including after creator retirement. Identity-only lookups, unreturned rows and entirely non-text fallback rows do not taint independent work. Unattributed current/historical inputs and physical erasure still require separate proof.

Native shared compaction summaries retain owned known-input manifests independently of the publishing run. A later turn records the prefix it actually adopts; confirmed deletion fences publication, cached model projections, refresh and outbound admission instead of serving a stale fallback. Legacy summaries without provenance are not certified retrospectively: their effective view rebuilds from available source-valid raw history without a total-history cap. Retained summary bytes and unknown historical ancestry are not thereby erased or proven safe.

Private history activity summaries also check their original native run's known inputs before hydration. A known-deleted source or unavailable original execution omits that activity, not independently submitted text or the original run outcome. Exact owner/thread checks and shared read locks serialize projection with deletion and receipt retirement. This does not erase stored events or recall activity delivered earlier.

Dashboard conversation summary/tag saves that started before cleanup of that exact conversation return 409 SOURCE_CONTENT_REVOKED. Refresh before submitting independently new notes. Cleanup and the conditional write serialize under a tenant read barrier; an unrelated conversation for the same customer is not blocked. Fresh edits, including independently supplied identical text, empty-tag clears and content-free assignment controls remain available. This stale-save fence does not certify historical metadata lineage or erase independent copies.

Build Or Update An Agent

Best permissions: Agent Builder.

1. create_agent with a BAREBONES or SUPPORT template.
2. update_agent_identity to set name, slug, or template.
3. update_agent_prompt for system instructions.
4. update_agent_model for model, temperature, reasoning effort, input token, step, or conversation history defaults.
5. update_agent_builtin_tools and update_agent_channel_settings for runtime behavior.
6. create_skill or install_skill_recipe for reusable instructions.
7. attach_skill_to_agent and reorder_agent_skills.
8. export_agent_configuration before and after changes so the client can show a diff.
9. test_agent or chat_playground to verify behavior.

Use import_agent_configuration only after reviewing the sanitized export payload.

Manage External MCP Servers For An Agent

Best permissions: Agent Builder plus access to the target agent.

1. list_mcp_catalog to inspect supported catalog entries.
2. activate_catalog_mcp_server to attach an API-key catalog server to an agent.
3. create_custom_mcp_server for a private Streamable HTTP or SSE server.
4. test_mcp_server before enabling it for production traffic.
5. update_mcp_server to change enabled tools or mark the config inactive.

The Platform MCP response returns sanitized config metadata only. It does not return stored secrets.

Manage API Keys Safely

Best permissions: Full Admin normal permissions plus exact API-key permissions.

1. list_api_keys and get_api_key to inspect metadata.
2. create_api_key for a new service account. Copy oneTimeRawKey; it will not be returned again.
3. update_api_key to narrow permissions, resource grants, allowed origins, rate limit, or expiry.
4. rotate_api_key when ownership changes or a key may be exposed.
5. revoke_api_key only with api_keys:revoke and explicit human approval.

Prefer rotation over creating duplicate long-lived keys.

Review Usage And Cost

Best permissions: Analytics preset.

Use get_usage, get_analytics, and get_billing_summary to answer questions about usage, cost, credits, and subscription state. These tools are read-only and safe for reporting clients.

Voice Operations

Best permissions: voice:read, and voice:write only for diagnostics cleanup. Local settings use agent configuration permissions.

1. list_voice_models and list_voices to inspect native options without claiming call readiness.
2. get_agent_configuration to check local voice settings for an agent.
3. update_agent_voice_settings to save local native overrides without remote sync.
4. list_voice_sessions, get_voice_transcript, and list_voice_tool_calls for captions, recording, usage, and settlement diagnostics.
5. clear_voice_tool_calls to clear transient Redis diagnostics.

Destructive Workflow Pattern

Use this pattern for delete_*, archive_skill, revoke_api_key, and deactivate_user tools.

1. Read the target resource first.
2. Ask the client to summarize impact in plain language.
3. Confirm the resource ID with a human.
4. Run the destructive tool once.
5. Read again to verify the result.
6. Check audit events for mcp.tool.destructive.

Do not grant destructive permissions to broad autonomous clients. Create a separate short-lived key for cleanup runs.

Related Docs

MCP Permissions

Map each workflow to the right preset, exact permissions, and destructive controls.

MCP Client Configs

Connect the MCP client before running these workflows.