Model Context Protocol for Agent Framework Developers
This page explains MCP from the perspective of an agent-framework developer,
walks through an end-to-end agent interaction, summarizes the stable
2026-07-28 protocol revision, and describes how Codex currently
handles MCP tools, resources, prompts, and server instructions.
3
Executive Summary
MCP is an interoperability boundary between an AI host and external systems.
It standardizes capability discovery, tool invocation, resource retrieval,
reusable prompt templates, results, errors, user-input requests, notifications,
caching, versioning, authentication, and transport.
MCP does not define the agent loop, planning, reasoning, memory, model selection,
context ranking, approval policy, or prompt assembly. The host application remains
responsible for deciding what the model actually sees.
The most important distinction is:
the agent runtime sees MCP; the model sees the runtime's projection of MCP.
Architecture
text
Model
|
|-- MCP client A --> GitHub MCP server ---> GitHub API
|-- MCP client B --> Database MCP server -> Database
`-- MCP client C --> Files MCP server ----> Filesystem]]>
Participants
-
Host: The application the user interacts with. It owns the
model call, agent loop, context policy, user experience, permissions, and
connections to one or more MCP servers.
-
Client: A protocol component inside the host that communicates
with one MCP server.
-
Server: A local or remote program that exposes external data
and capabilities through MCP.
Layers
-
Data layer: JSON-RPC 2.0 requests, results, errors,
capability discovery, primitives, utilities, and extensions.
-
Transport layer: Standard input/output for local subprocesses
or Streamable HTTP for remote services, including framing and authorization.
What MCP Standardizes
- Version and capability discovery.
- Typed tool discovery and invocation.
- Addressable contextual data and resource templates.
- Reusable, parameterized prompt templates.
- Results, structured content, errors, progress, and cancellation.
- User elicitation and multi-round-trip interactions.
- Caching and change notifications.
- Local and remote transports and HTTP authorization conventions.
- Negotiation of optional extensions such as Tasks and MCP Apps.
What MCP Does Not Standardize
- Planning, reasoning, or the agent loop.
- Conversation memory or history compaction.
- Which model or provider to call.
- How tools are selected, approved, or presented to users.
- How resources are ranked, chunked, summarized, or injected.
- The instruction priority assigned to server-supplied text.
- How tool results are converted into model messages.
Core Primitives
| Primitive |
Purpose |
Typical controller |
What can reach the model |
| Tools |
Executable operations such as search, query, create, or modify. |
Model, subject to host policy. |
Name, description, input schema, output schema, and execution result. |
| Resources |
Addressable, normally read-only context such as files, schemas, and records. |
Host, user, or model through a host-defined interface. |
Only descriptors and content the host chooses to expose. |
| Prompts |
Reusable, parameterized message and workflow templates. |
Normally the user or host. |
The instantiated messages returned by prompts/get. |
| Elicitation |
Requests for additional user information or confirmation. |
Server to host to user. |
Usually handled by UI; it does not have to enter model context. |
| Extensions |
Optional independently negotiated functionality. |
Host and server. |
Depends on the extension; a task handle may be visible while an app UI may not be. |
End-to-End Agent Example
Consider the request: Investigate today's checkout errors, consult our
runbook, and open a GitHub issue if this is a new regression.
-
The host connects to Sentry, internal-documentation, and GitHub MCP servers.
-
It discovers protocol versions and capabilities, then retrieves tool,
resource, and prompt catalogs as needed.
-
The host converts selected MCP tools into the model provider's native
function/tool representation.
-
The host may retrieve a relevant runbook resource and include a bounded
excerpt in model context.
-
The model calls a Sentry search tool. The host validates the call, applies
approval policy, and routes
tools/call to the correct server.
-
The server calls Sentry and returns text, structured JSON, media, or links
to additional resources.
-
The host converts the useful result into a model-visible tool-result message.
-
The model searches existing GitHub issues and decides whether to create one.
-
If confirmation is required, the server returns
resultType: "input_required". The host gathers user input and
retries the original operation.
-
A long operation may return a Tasks extension handle, which the host polls
or updates.
-
Tool or resource change notifications may cause the host to refresh future
catalogs.
How Resources Reach an Agent
Resources use a two-stage process. A list call returns catalog metadata, not
necessarily the underlying content. A later read call retrieves the content.
The host then decides whether and how to provide it to the model.
Resource Discovery
json
server
{
"jsonrpc": "2.0",
"id": 1,
"method": "resources/list",
"params": {}
}
// Server -> client
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"resources": [
{
"uri": "docs://payments/refund-policy",
"name": "Refund policy",
"description": "Current refund rules",
"mimeType": "text/markdown"
}
],
"ttlMs": 300000,
"cacheScope": "private"
}
}]]>
At this point the client has a descriptor: URI, name, description, MIME type,
and optional metadata. The actual policy text has not necessarily entered
model context.
Resource Reading
json
server
{
"jsonrpc": "2.0",
"id": 2,
"method": "resources/read",
"params": {
"uri": "docs://payments/refund-policy"
}
}
// Server -> client
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"resultType": "complete",
"contents": [
{
"uri": "docs://payments/refund-policy",
"mimeType": "text/markdown",
"text": "# Refund policy\nRefunds are available within..."
}
],
"ttlMs": 300000,
"cacheScope": "private"
}
}]]>
Host Choices
After reading a resource, a host may:
- Insert all or part of its text into the next model request.
- Present it as a user-selected attachment.
- Index it for retrieval and inject only relevant chunks.
- Summarize or truncate it to meet context limits.
- Display it without making it model-visible.
- Reject it because of permissions, provenance, type, or size.
Resource Templates
resources/templates/list exposes parameterized URIs, for example:
text
How Prompts Reach an Agent
MCP prompts are reusable, parameterized message templates. Unlike tools,
prompts are normally user-controlled: a host may render them as slash commands,
menus, workflow starters, or form-driven actions.
Prompt Discovery
json
server
{
"jsonrpc": "2.0",
"id": 3,
"method": "prompts/list",
"params": {}
}
// Server -> client
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"resultType": "complete",
"prompts": [
{
"name": "review_pull_request",
"title": "Review pull request",
"description": "Reviews a PR using the team's standards",
"arguments": [
{
"name": "pr_number",
"description": "Pull request number",
"required": true
}
]
}
],
"ttlMs": 300000,
"cacheScope": "public"
}
}]]>
Prompt Expansion
json
server
{
"jsonrpc": "2.0",
"id": 4,
"method": "prompts/get",
"params": {
"name": "review_pull_request",
"arguments": {
"pr_number": "123"
}
}
}
// Server -> client
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"resultType": "complete",
"description": "Review PR #123",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Review pull request #123. Check API compatibility..."
}
}
]
}
}]]>
The host can append the returned messages to the conversation and start a
model turn. Prompt messages may also include embedded resources. MCP defines
the returned structure but does not require a particular command UI or
instruction priority.
A server does not push a prompt into model context merely by advertising
it. The client must list it, select it, retrieve it, and deliberately add
the returned messages to a model request.
How Codex Implements MCP
Tools
Codex discovers MCP tools and converts each selected definition into the
model provider's tool representation. The model sees a callable namespace,
tool name, description, and schema. When the model emits a tool call, Codex
routes it to the owning MCP client and returns the server result as a
model-visible tool result.
Resources
Codex maps the MCP resource primitive into three internal model-callable tools:
list_mcp_resourceslist_mcp_resource_templatesread_mcp_resource
text
Resource contents are therefore fetched on demand rather than copied into
context when the server connects. Codex retains control over authorization,
serialization, visibility, and truncation.
The Codex App Server also exposes mcpServerStatus/list and
mcpServer/resource/read. A Codex UI can use these operations to
implement a resource browser or explicit attachment picker without asking
the model to perform the read.
Prompts
Current Codex does not expose MCP prompts/list or
prompts/get as model tools, slash commands, or documented App
Server operations. A server may advertise prompts according to MCP, but
current Codex does not automatically inject or render them.
This illustrates an important compatibility rule:
a primitive supported by the MCP specification is not necessarily
implemented by every MCP host.
Server Instructions
Codex consumes the server's top-level instructions value as
server-wide guidance associated with the server's model-visible tool
namespace.
json
This field is appropriate for cross-tool workflows, constraints, rate limits,
and high-level usage guidance. Codex documentation recommends keeping the first
512 characters self-contained so that the most important guidance is available
during tool selection.
Prompt-Like Workflows in Codex
| Requirement |
Recommended Codex mechanism |
| Short guidance applying to every tool from a server |
MCP server instructions |
| Reusable multi-step workflow |
Skill |
| Repository-specific durable instructions |
AGENTS.md |
| Live contextual data |
MCP resource |
| Dynamic operation or lookup |
MCP tool |
| Server-generated dynamic instructions when a skill is unsuitable |
A narrowly scoped read-only MCP tool whose result is treated as untrusted content |
MCP 2026-07-28 Revision
The stable 2026-07-28 revision is a breaking revision relative
to 2025-11-25. Its central architectural change is a move from
connection-oriented protocol sessions to self-contained, stateless requests.
Stateless and Sessionless Core
- The
initialize/notifications/initialized handshake is removed.
- The
Mcp-Session-Id HTTP header is removed.
- Every request carries protocol version and client capabilities in
_meta.
- Clients should identify themselves on each request.
- Servers should identify themselves in response
_meta.
-
Servers must implement
server/discover so clients can discover
supported versions, capabilities, identity, and optional instructions.
-
Version mismatches return
UnsupportedProtocolVersionError.
Explicit Stateful Workflows
Application state is still allowed, but it is represented by explicit handles
instead of hidden connection state.
text
{ "basket_id": "bsk_123" }
add_item(
basket_id = "bsk_123",
sku = "ABC"
)]]>
This makes state handles visible to the model or host and allows any stateless
server replica to process the next request.
Multi Round-Trip Requests
Server-to-client requests such as elicitation are represented by an interim
result. The client gathers the requested information and retries the original
request with a new JSON-RPC request ID.
json
All successful results now include a resultType, normally
complete or input_required.
Notification Redesign
-
The standalone HTTP GET stream and resource subscribe/unsubscribe methods
are replaced by
subscriptions/listen.
-
Clients explicitly subscribe to tool, prompt, resource-list, or individual
resource changes.
- Notifications are tagged with a subscription identifier.
-
Request-specific progress and messages remain on the response stream of the
related request.
Retry and Idempotency
SSE event IDs, Last-Event-ID, and protocol-level stream resumption
are removed. If a response stream breaks, the client reissues the operation
with a new request ID.
Agent frameworks should protect side-effecting tools with application-level
idempotency keys or outcome lookup. Retrying a search is harmless; blindly
retrying a payment or issue creation can duplicate an action.
Caching and Deterministic Catalogs
-
Tool, prompt, and resource lists and resource reads include
ttlMs and cacheScope.
-
Tool lists should be returned in deterministic order to improve client and
model prompt-cache behavior.
-
A host may use cached catalogs or resource contents until their freshness
window expires.
Richer Tool Schemas
- Tool schemas support substantially more JSON Schema 2020-12 features.
- Composition, conditionals,
$ref, and $defs are supported.
outputSchema is less restricted.-
structuredContent can be any JSON value, including an array,
scalar, or null.
-
Frameworks may need to simplify MCP schemas for model providers whose native
function-calling schema supports only a subset.
First-Class Extensions
Clients and servers negotiate optional extensions through the
capabilities.extensions map using reverse-DNS identifiers.
-
io.modelcontextprotocol/tasks: durable long-running operations
using task handles and get, update, and cancel operations.
-
io.modelcontextprotocol/ui: MCP Apps, in which a server can
provide interactive UI rendered by a compatible host.
Deprecated Features
| Deprecated feature |
Recommended migration |
| Roots |
Use explicit tool parameters, resource URIs, or server configuration. |
| Sampling |
Integrate the server directly with an LLM provider when server-side inference is required. |
| Logging |
Use standard error for local servers or OpenTelemetry for structured observability. |
| HTTP plus SSE transport |
Use Streamable HTTP. |
| OAuth Dynamic Client Registration |
Use Client ID Metadata Documents where supported. |
HTTP, Observability, and Authorization
- Standard
Mcp-Method and Mcp-Name routing headers.
- Optional tool-parameter-to-header mapping through
x-mcp-header.
- W3C trace-context propagation in
_meta.
- OAuth authorization-response issuer validation.
- Binding persisted client credentials to the issuing authorization server.
- More explicit OpenID Connect application-type registration.
What the Model Sees
The following protocol details are normally runtime-only:
- Protocol version and
server/discover.
- Capability and extension negotiation.
- JSON-RPC IDs and HTTP routing headers.
- OAuth tokens and authorization-server metadata.
- Cache TTLs and cache scope.
- Subscription identifiers and trace context.
- Connection identity or server replica.
The principal model-visible effects of the new revision are:
-
Explicit state handles: State that was hidden in a connection
may now appear in tool results and subsequent tool arguments.
-
More stable tool definitions: Deterministic ordering and
caching make tool sections more stable across model calls.
-
Richer schemas and output shapes: Models may receive more
expressive constraints and array or scalar structured outputs.
-
Cleaner interruption handling: Hosts can handle
input_required and expose only the final result to the model.
-
More explicit scope: Replacing Roots with parameters and
resource URIs can make scope visible in tool calls.
-
Less nested access to the host model: Deprecating Sampling
reduces implicit server-initiated model completions and cross-server context.
-
Dynamic tool changes: Notifications may cause future model
calls to receive a different tool registry.
Framework Design Recommendations
-
Keep the MCP protocol adapter separate from the model-provider tool adapter.
-
Support both the modern
2026-07-28 protocol and legacy
initialization-based servers during migration.
-
Treat every request as self-contained and avoid connection-scoped application
state.
-
Design explicit, opaque, authorized, expiring handles for stateful workflows.
-
Add idempotency controls to side-effecting tools.
-
Validate full MCP JSON Schema but normalize it for model-provider limitations.
-
Cache catalogs and resource contents according to
ttlMs and
cacheScope.
-
Handle elicitation and task polling outside the main model loop when the
model does not need to see the intermediate protocol exchange.
-
Never expose authentication tokens, trace metadata, or transport details to
the model unless there is an explicit, safe reason.
-
Treat server instructions, prompt templates, resource contents, tool
descriptions, and tool results as untrusted external content.
-
Apply explicit size bounds, provenance labels, and instruction-priority
rules before adding server-supplied content to model context.
Sources