MCP Embedding Levels Framework
MCP apps embed in AI clients at one of three levels – read-only, actions, or agent-resident – distinguished by what the agent can do with the underlying product. Each level has different security models, design demands, costs, and value to the user. The level you ship at is one of the highest-leverage product calls in an MCP roadmap, and it is routinely made by default rather than deliberately – usually by an engineer reading the spec on a Friday and shipping whatever the docs make easiest.
This guide lays out the three levels, what each one entails, and how to decide which one to ship at. It uses the working vocabulary in our MCP terminology guide.
Match Level to What the Product Can Defend
The level you ship at is not a measure of ambition. It is a measure of what the product can defend, and what the company is committed to becoming. A read-only MCP app says "the agent should know what we know." An actions MCP app says "the agent should be able to act on what we hold." An agent-resident MCP app says "the agent is part of how this product operates." Three different commitments, three different costs, three different futures.
The Three Embedding Levels
| Level | What the agent can do | Risk | Time to ship | Typical cost (partner-built) | Best for |
|---|---|---|---|---|---|
| Read-only | Query and read data; cannot change anything | Low | ~1 quarter | $100K–$300K | First MCP ship; defensive presence; data-rich products |
| Actions | Read + execute mutations (create, update, delete, send) | Medium | ~2 quarters | $300K–$700K | Capability products; system-of-record products with mature safety story |
| Agent-resident | Operates as a first-class user with identity, state, and internal participation | High | Multi-quarter rebuild | $1M+ | Companies whose strategic premise is agent-first |
Read-Only MCP Apps
A read-only MCP app is an MCP app whose tools only query data and never modify it. The agent can answer questions and reason against your system – your customers, your tickets, your inventory, your documents – but cannot change anything inside it.
Concretely, the tools exposed at this level are all queries: search_customers, get_ticket, list_invoices, find_in_knowledge_base. There are no create_, update_, or delete_ verbs. Resources may also be exposed for direct data reads.
Read-only is the lowest-risk, fastest-to-ship version of MCP presence. For some products it is the right ceiling, not a stepping stone – particularly destination products that benefit from exposing their data to agents without rebuilding the destination experience inside the AI client.
Sample read-only tool definition
A representative read-only tool exposes a clear query with informative parameters and citation-friendly response shape:
{
"name": "search_customers",
"description": "Search the customer database by name, email, or company. Returns up to 50 matching customers with their basic info. Use when the user asks about a specific customer or wants to find customers matching criteria.",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query – name, email address, or company name"
},
"limit": {
"type": "integer",
"description": "Maximum results to return (1-50)",
"default": 20,
"minimum": 1,
"maximum": 50
},
"include_inactive": {
"type": "boolean",
"description": "Whether to include inactive/archived customers",
"default": false
}
},
"required": ["query"]
}
}The response should include enough metadata for the agent to cite – record IDs, links to the canonical record in your product, last-updated timestamps. This lets the user verify the answer and click through to the source.
Read-only design problems
Three product problems matter at this level:
- Retrieval quality. Are tools well-named so the agent picks the right one? Do they return the right shape of data so the agent does not need three calls when one would do?
- Reasoning legibility. Does the data include enough metadata for the agent to cite – record IDs, links to canonical records, timestamps – so the user can verify the answer?
- Pagination. Are large result sets paginated in a way the agent can iterate over without confusion? Cursor-based pagination tends to work better than offset-based for agents.
Read-only security
The security story is comparatively simple. The user grants read access at install. The agent reads. Mutations cannot happen by accident because the surface does not allow them. Enterprise procurement teams approve faster for read-only MCP apps.
When to ship at level 1
Ship at level 1 (read-only) when:
- Your product holds data the agent benefits from reading
- Your buyer’s primary unmet need is I want the agent to know what we know
- Your safety, audit, or auth story is not yet mature enough to defend writes
- You want the fastest path to MCP presence with the lowest procurement friction
Actions-Level MCP Apps
An actions MCP app is an MCP app whose tools include mutations – create, update, delete, and send operations the agent can execute on the user’s behalf. The agent can draft and send the email, file the ticket, update the record, schedule the meeting, post the invoice, charge the card.
The tool surface at this level includes both queries and verbs: create_ticket, update_customer, send_invoice, book_meeting. The agent reads to understand what the user wants and writes to do it.
The design demands jump sharply from read-only to actions. Four problems become real product surface that did not exist at level 1.
Idempotency
The agent will retry. Sometimes because the network glitched, sometimes because it second-guessed itself, sometimes because the user said do that again. Write tools must tolerate retries without producing duplicates.
The standard pattern is idempotency keys. The client (the AI client or the agent runtime) generates a unique idempotency key for each logical operation. The server stores recent keys with their results, and repeat calls with the same key return the cached result rather than re-executing.
{
"name": "send_invoice",
"description": "Send an invoice to a customer via email. Use when the user wants to bill a customer. Returns the sent invoice ID and a confirmation that it was delivered.",
"inputSchema": {
"type": "object",
"properties": {
"customer_id": { "type": "string", "description": "Customer to invoice" },
"amount_cents": { "type": "integer", "description": "Amount in cents", "minimum": 1 },
"currency": { "type": "string", "default": "USD" },
"idempotency_key": {
"type": "string",
"description": "Unique key for this invoice operation. If the same key is provided twice within 24 hours, only one invoice is sent and the original result is returned. The agent should generate a new UUID per logical operation."
}
},
"required": ["customer_id", "amount_cents", "idempotency_key"]
}
}Stripe’s API is the reference implementation for idempotency keys. The cost of getting idempotency wrong: the user discovers they sent the same invoice three times, or charged the customer twice for one purchase.
Reversibility
Some writes are reversible (update_customer, where the previous state is restorable). Some are not (send_email, charge_card, delete_* without soft-delete).
The product should make reversible writes obviously reversible. Three patterns work:
- Soft delete with undo window.
delete_customerdoesn’t actually delete; it marks the record as deleted with a 30-day restoration window. Returns anundo_tokenthe agent can pass torestore_customerif the user changes their mind in the same conversation. - Update with revision history.
update_customerwrites a new revision, preserving the previous state. The agent can describe what changed and offer to revert. - Two-phase commit for high-stakes operations.
prepare_chargereturns a token;execute_chargeactually runs. The agent must show the prepared charge to the user before calling execute.
Irreversible writes deserve heavier confirmation, both from the agent (are you sure you want to send this?) and from the system (rate limits, two-step confirms for high-stakes operations).
Intent preview
Before the agent executes a write, the user should be able to see and approve what is about to happen. This is partly the host client’s job – Claude, Copilot, and the more mature clients have intent-preview UI built in – but it is also yours: tool parameters need to be expressive enough that the preview is informative.
Bad: execute_send_email(payload: {...}). The preview can only say the agent wants to call execute_send_email. The user has no idea what the email contains.
Good: send_email(to: "alice@acme.com", subject: "Re: contract review", body: "Hi Alice, ...", attachments: [...]). The preview shows the user exactly what is about to be sent, and the user can edit before approving.
The principle: parameters should be human-meaningful, not opaque blobs. Pass structured data (recipient, subject, body) rather than serialized payloads.
Audit trail
Every write through the MCP app should be attributable. Per-invocation logs that capture: user identity, host AI client, session identifier, tool invoked, parameters passed, result, timestamp.
Enterprise buyers will require this. Consumer buyers will appreciate it the first time something goes wrong. The audit log should be queryable by the customer’s admin, not just by your support team. See MCP auth and security for the customer-facing audit log surface bar.
Common Failure Mode
The most common failure mode in MCP work is shipping `delete_*` and `send_*` tools without reversibility or audit, then watching the first incident erode trust faster than the feature earned it. The second-most-common failure is shipping level 2 with the audit log built but not exposed to customer admins – the audit exists technically and not procedurally, which is the worst of both worlds. If you cannot expose the audit log to customer admins on day one, you are not ready for level 2.
When to ship at level 2
Ship at level 2 (actions) when:
- The user’s job-to-be-done in the AI client requires changing your system, not just reading it
- You have built (or are committed to building) idempotency keys, soft-delete or revision-history reversibility, intent-preview-friendly parameter shapes, and per-invocation audit logs
- The business value of writes clearly exceeds the cost of doing them properly
Agent-Resident MCP Apps
The deepest level is the one almost no product team is at today, and the few who are have rebuilt themselves around it.
An agent-resident MCP app does not just let the agent invoke tools. It treats the agent as a first-class user of the product, with its own identity, its own audit trail, its own relationships with other entities, and its operation across time. Your product is not being read or written by the agent; it is being inhabited by the agent.
Concretely, the difference between level 2 and level 3 is the difference between exposing create_ticket (a single operation) and exposing a tool surface rich enough that the agent can run an entire support triage workflow – read the ticket, draft a response, escalate to a specialist if needed, mark resolved if it can, follow up tomorrow if it can’t, and accumulate context across all of that as a coherent participant in the support queue.
Three structural changes
The agent has its own identity in your system, separate from any human user. There is a row in your users or service_accounts table for the agent.
service_accounts
id: srv_acct_42
type: "agent"
human_principal_user_id: usr_178 // user the agent acts on behalf of
host_client: "claude.ai"
permissions_envelope: { ... }
created_at: 2026-01-15The agent participates in your product’s internal mechanisms – assignments, notifications, escalations, status changes – alongside human users. A ticket can be assigned to an agent. A workflow can be triggered by an agent’s action.
tickets
id: tkt_91
assigned_to: srv_acct_42 // assigned to an agent
status: "in_progress"
agent_metadata: {
confidence_score: 0.84,
escalation_threshold: 0.6
}The agent accumulates state across sessions. It is not amnesiac between calls. It remembers what it tried last week, who it has been working with, which approaches have worked. This requires a persistent memory store the agent can read and write across sessions, scoped to the agent’s identity.
Architectural commitment
Level 3 requires rethinking the product’s permission model, identity model, audit model, notification model, and often the underlying data model. It requires designing for an actor that does not have a coffee cup, does not get tired, and is operating in parallel sessions on behalf of multiple users.
When to ship at level 3
Ship at level 3 (agent-resident) when the strategic premise of the company is that agents are a primary user class, not a guest, and the product is being built or rebuilt around that premise. Do not ship at level 3 when the company has not made that strategic commitment – level 3 attempted as a product extension fails, because it requires changes to identity, permissions, audit, notification, and often data models that retrofits cannot supply.
Choosing and Sequencing Levels
Most product teams should ship level 1 first, expand to level 2 when the safety story is mature, and consider level 3 only if the company is rebuilding around an agent-first thesis.
| Your situation | Recommended level |
|---|---|
| First MCP ship, no prior MCP experience | Level 1 (read-only) |
| Have shipped read-only, ready for writes, have safety infrastructure | Level 2 (actions) |
| Agent-first startup; product designed for agents from inception | Level 2 or 3 (depending on architectural readiness) |
| Established product wanting to extend into MCP | Level 1 first; level 2 by quarter three |
| Destination product with cannibalization risk | Level 1 only; do not expand |
| System of record with deep agent-mediated workflows in your audience | Level 2 within first year; level 3 only with explicit strategic commitment |
Progression versus leap
Most teams should progress: level 1 first, learn, level 2 when ready, level 3 only with strategic commitment. A small minority – usually agent-first startups – should leap directly to level 2 or 3 because the product is being designed for that level from inception.
The progression model is both a defensive strategy and a learning strategy. Read-only MCP apps generate the data – what users actually ask for, where the agent gets stuck, what tools get invoked – that informs actions design. Level 2 generates the safety and audit infrastructure that informs agent-resident design. Skip levels and the next level is built on instinct rather than evidence.
Questions Before Picking a Level
What is the user's job-to-be-done that requires more than reading? If you cannot answer in one sentence, level 1 is correct. What is the worst write the agent can do, and what is the recovery path? If the answer is "we'd lose data" or "we'd send something we cannot take back," level 2 safety infrastructure is non-negotiable. What is your audit story for agent-mediated actions? If you cannot produce a per-action audit log on day one, level 2 is premature. What changes about our product if the agent is a first-class user? If the answer is "very little," you are not at level 3.
The level you ship at is not a measure of ambition. It is a measure of what the product can defend. Most teams’ honest answer is level 1 first, level 2 by quarter three, level 3 only if the company is rebuilding around it.
Related Guides
- What to Call MCP Apps: Terminology Guide
- How to Embed Your App in AI Clients with MCP
- MCP Strategy Decision Framework
- MCP Auth and Security – Auth design that supports the level you ship at
- MCP Build vs Buy – Cost ranges per embedding level
Frequently Asked Questions
What is the difference between read-only and actions in MCP?
Read-only MCP apps expose only query tools (the agent can read data but cannot change it). Actions MCP apps expose query and mutation tools (the agent can create, update, delete, send). Actions require idempotency keys, reversibility patterns (soft delete, revision history, two-phase commit), intent-preview-friendly parameter shapes, and per-action audit logs that read-only does not.
Is read-only MCP enough for most products?
For first ships, almost always yes. Read-only is the right starting point unless the product team has prior MCP experience and a defensible safety story for writes. For some destination products, read-only is the permanent right level, not a stepping stone.
What is agent-resident MCP?
An agent-resident MCP app treats the agent as a first-class user of the product, with its own identity in your data model, accumulated state across sessions, and participation in the product's internal mechanisms (assignments, notifications, escalations). Almost no products are at this level in 2026; those that are have rebuilt around the agent-first thesis.
Can I ship MCP write tools without idempotency?
You can ship them, but you should not. Agents will retry, and write tools without idempotency produce duplicate records, duplicate emails, or duplicate charges – incidents that erode trust faster than the feature earned it. Idempotency keys (UUID-based, with server-side caching of recent results) are non-negotiable for level 2.
What is an idempotency key in an MCP tool?
An idempotency key is a unique identifier the agent passes with each write operation. The server stores recent keys with their results; if the same key is sent twice within a window (typically 24 hours), the server returns the original result rather than re-executing the operation. This makes retries safe and prevents duplicate writes. Stripe's API is the reference implementation.
How do you implement reversibility in MCP write tools?
Three patterns: soft delete with undo window (operations don't immediately destroy data; they mark records and offer restoration tokens), update with revision history (writes preserve previous state and expose a revert path), and two-phase commit (prepare-and-execute for high-stakes operations). Pick the pattern per operation based on blast radius.
How long does it take to ship at each MCP embedding level?
Level 1 (read-only), single client: one quarter ($100K–$300K partner-built). Level 2 (actions), single client: two quarters ($300K–$700K partner-built). Level 3 (agent-resident): multi-quarter, often a multi-year program ($1M+).
Should I skip read-only and go straight to actions?
Most teams should not. Read-only generates the usage data and infrastructure that informs the actions design. Skipping read-only is appropriate only for agent-first startups whose product is designed for level 2+ from inception.
What happens if I ship the wrong embedding level?
Shipping too low leaves user value on the table; shipping too high produces incidents the safety infrastructure cannot defend. The first failure mode (too low) is recoverable in a quarter. The second (too high) can produce trust damage that takes a year to recover from.
Can I have different MCP embedding levels per host client?
Yes, and this is sometimes the right move. Ship level 2 actions on Claude (where per-tool consent and intent-preview UI are mature) and level 1 read-only on Cursor (where per-tool consent is weaker). Match the embedding level to what the host client's safety surface can support.