TechOneDigital Scope one production MCP capability

Based on the current stable MCP specification

Production implementation

Production MCP needs explicit contracts, accountable ownership and operational evidence.

A working MCP connection is only the start. Production readiness requires controlled side effects, observable outcomes, reliable recovery and clear ownership across the host, server and system of record.

For

Engineering leads and service owners

Use when

A working MCP connection must become an operated service.

Outcome

A capability contract, release evidence, reliability controls and an operating model.

Technical guide by , Founder & Technology Consultant.

TechOne architecture position

MCP standardises discovery and invocation. It does not standardise the business meaning of success. Production architecture must make that meaning testable across the host, transport, server and system of record.

Contract before SDK

A tool is a production interface, not a prompt convenience.

Its name, schema, permission, failure behaviour and evidence model become part of the runtime surface seen by hosts and models. Define that contract before choosing framework decorators.

Illustrative operation contract

Expose a business capability, not a raw API estate.

This record is deliberately implementation-neutral. It states what must be true for the capability to be safe to build and operate.

Stable capability identity
An immutable internal server ID, tool name and contract version, distinct from human-readable titles.
TechOne recommendation
Purpose and non-goals
The business outcome the capability supports, the decisions it must not make and the environments or records it must not reach.
TechOne recommendation
Input schema
A constrained JSON Schema with required fields, formats, ranges and additional-property behaviour. The server validates every call independently of the model.
Protocol fact and TechOne recommendation
Output schema
A structured result contract that distinguishes business data, evidence, warnings and machine-actionable error states.
Protocol-supported and TechOne recommendation
Authorisation contract
Required audience, scopes, principal types, tenant rules and object-level checks.
Protocol fact and TechOne recommendation
Approval contract
The consequence class, approval trigger, information shown to the approver and the exact request digest to which approval is bound.
TechOne recommendation
Side-effect and idempotency contract
Whether the operation reads, proposes, creates, updates or irreversibly acts; the command identifier and duplicate-call behaviour for mutations.
TechOne recommendation
Timeout and cancellation contract
Client deadline, server budget, downstream budget, cancellation propagation and the state reported when work may continue after disconnection.
Protocol-supported and TechOne recommendation
State contract
Any explicit handle, its owner, retention, expiry and recovery behaviour. The current MCP specification has no protocol-level session.
Protocol fact and TechOne recommendation
Freshness contract
Source timestamp, cache eligibility, ttlMs, cacheScope and invalidation path for discoverable or readable data.
Protocol fact and TechOne recommendation
Evidence contract
Trace, policy, approval, downstream and outcome records needed to explain a production action without logging secrets.
TechOne recommendation
Ownership and SLO
Named business and technical owners, availability and latency objectives, support path, error budget and retirement decision.
TechOne recommendation

Implementation sequence

Move from contract to evidence, then to operation.

  1. 01

    Design

    Is this a focused capability with a clear owner, consequence and trust boundary?

    Evidence: Contract draft, data-flow map, threat model and proposed SLO.TechOne recommendation
  2. 02

    Verify

    Does the implementation reject invalid identity, inputs, states and protocol metadata before it reaches the backend?

    Evidence: Contract, security, tenancy, failure and compatibility test results.TechOne recommendation
  3. 03

    Register

    Has the organisation recorded the publisher, endpoint, transport, version, schemas, owner and approved environments?

    Evidence: Private catalogue record and schema fingerprint.TechOne recommendation
  4. 04

    Publish

    Are only the approved tools visible to the intended principals and clients?

    Evidence: Policy decision, filtered tools/list response and release approval.Protocol-supported and TechOne recommendation
  5. 05

    Operate

    Can the team observe latency, errors, policy decisions, approvals, cost and downstream health by capability and tenant?

    Evidence: Dashboards, trace samples, audit records and alert tests.TechOne recommendation
  6. 06

    Change

    Does a schema, description, authorisation or side-effect change trigger compatibility testing and the right level of re-approval?

    Evidence: Semantic diff, version decision, migration test and updated catalogue record.TechOne recommendation
  7. 07

    Retire

    Can consumers move without silent breakage, orphaned credentials or retained state?

    Evidence: Usage inventory, deprecation notice, credential revocation and state-retention outcome.TechOne recommendation

Failure is part of the contract

A retry must not become a duplicate business action.

Transport recovery, business idempotency and downstream confirmation are separate mechanisms. Writes require an explicit command identity and a result that can be reconciled.

Protocol fact and TechOne recommendation

Use stateless transport without hiding business state.

At the protocol layer, the current MCP specification allows any request to reach any compatible instance. Persist required workflow state behind an explicit, opaque handle, make it available through a shared durable store or deliberately controlled instance affinity, and bind the handle to the verified principal.

TechOne recommendation; stable optional Tasks extension where capability support is negotiated

Separate request completion from business completion.

A transport response may confirm acceptance while downstream work remains in progress. Return a durable job or task reference and an unambiguous terminal outcome for long-running operations.

TechOne recommendation

Do not retry consequential calls blindly.

Timeout does not prove that a write failed. Give mutations a stable command ID, deduplicate server-side and expose a status lookup before retrying.

Protocol-supported and TechOne recommendation

Budget time across the whole chain.

Define separate host, gateway, server and downstream deadlines. Propagate cancellation where possible and document any work that cannot be stopped safely.

TechOne recommendation

Bound concurrency before it reaches the system of record.

Apply per-principal, tenant, tool and downstream limits. A model can generate valid calls faster than a legacy service can process them.

Protocol fact and TechOne recommendation

Design failure as data the model can use safely.

Distinguish protocol errors from tool execution errors. Return bounded, actionable business errors without leaking internal topology, credentials or sensitive records.

Protocol fact and TechOne recommendation

Test both protocol eras during migration.

The current request lifecycle is materially different from the earlier `initialize` handshake and session model. Negotiate deliberately and test the clients that will actually consume the server.

Protocol fact and TechOne recommendation

Use Streamable HTTP for shared remote services and stdio for deliberate local process integration.

The transports have different process, network, cancellation and isolation boundaries; they are not interchangeable deployment labels.

Performance evidence

Measure the full call path, not just server response time.

  • Tool catalogue size and definition tokensSplit broad servers, filter by authorisation and defer loading where the host supports it. More visible tools increase context cost before any API call occurs.TechOne recommendation supported by official client guidance
  • Prompt-cache stabilityReturn tools in deterministic order and avoid unnecessary metadata churn.Protocol recommendation
  • Discovery and list cache hit rateTune ttlMs from observed change frequency. Invalidate on relevant notifications only when the client supports, subscribes to and receives them; otherwise expire or refetch on the documented freshness boundary.Protocol-supported and TechOne recommendation
  • p50, p95 and p99 end-to-end latencyBreak down host, gateway, server and downstream spans rather than optimising only the MCP handler.TechOne recommendation
  • Queue time and active concurrencyProtect constrained downstream systems before latency turns into cascading timeout and retry traffic.TechOne recommendation
  • Timeout, cancellation and orphan-work rateIdentify operations that continue after the client has gone away and make their recovery path explicit.TechOne recommendation
  • Tool success versus business successMeasure accepted, completed, rejected, partially applied and compensated outcomes separately.TechOne recommendation
  • Schema-validation and policy-denial rateUse failures to improve the contract or client behaviour; do not weaken validation to make the metric disappear.TechOne recommendation
  • Cost per completed business outcomeCombine model use, retries, review, integration and downstream cost rather than reporting tool-call volume as value.TechOne recommendation

Release evidence

The negative path is a production feature.

ScenarioExpected behaviourEvidence
Modern protocol request reaches any healthy compatible instanceNo connection affinity is required for protocol state; the request carries its protocol version and client capabilities. Application state behind an explicit handle remains reachable through a shared durable store, or the deployment deliberately enforces and tests controlled instance affinity.Load-balancer test across multiple instances with trace correlation and state recovery evidence.
Unsupported protocol versionThe server returns the defined structured error and advertises supported versions rather than silently interpreting the request.Captured HTTP and JSON-RPC response.
Mcp-Method or an applicable Mcp-Name disagrees with the bodyThe server rejects the request with HTTP 400 and HeaderMismatch -32020.Negative transport conformance test.
Caller has a narrower scope or different tenantThe visible catalogue and object access are reduced; no cached private result crosses the authorisation boundary.Two-principal comparison with cache instrumentation.
Two servers expose the same tool namePolicy, logs and approval UI retain an unambiguous server-qualified identity.Aggregation and routing test.
Tool definition changes after approvalThe release is blocked or moved through semantic review and re-approval before the new contract is active.Schema and description diff in the release record.
Expired or stolen state handle is presented by another principalThe server rejects the call and does not reveal whether another user’s state exists.Cross-principal and expiry test.
Client times out during a writeA repeated command cannot duplicate the side effect; the client can query the original command outcome.Injected timeout with downstream record count and command log.
A resource changes before ttlMs expiresA client that supports, subscribes to and receives the relevant change notification invalidates the cached result. Other clients expire or explicitly refetch it according to the documented freshness contract.Subscribed-client invalidation test, fallback TTL or refetch test, and resource timestamps.
Downstream system slows or returns partial failureConcurrency remains bounded, timeouts do not cascade and the tool returns an accurate recoverable state.Fault-injection trace and SLO result.
SSE response stream is closed by the clientThe server treats the close as cancellation, stops work where practical and emits no further messages on that request.Cancellation test with server and downstream traces.
OAuth metadata redirects to a private or link-local addressThe client or controlled egress path blocks the request.SSRF test with network-deny evidence.

TechOne design recommendation

Validate the decision, not only the tool call.

A permitted tool call can still carry out the wrong decision. Evaluate representative workflows for the selected tool, arguments, source evidence and resulting business outcome, including refusal and escalation when evidence is insufficient. Repeat these scenarios after changes to models, prompts, tools or knowledge sources. Set release gates by consequence: critical failures should block release even when the overall pass rate is high. Agree acceptance criteria with business, technical and security owners. Test results support a release decision; they do not guarantee future behaviour.

  1. 01

    Correct request and business outcome

    Check: Check the selected tool, target entity, arguments and interpretation of the source result against the intended task.

    Expected response: Confirm the expected business state in the source system. An accepted call or HTTP success is insufficient evidence.

  2. 02

    Ambiguous account or record

    Check: Use representative cases with similar names, several matching records or missing identifiers.

    Expected response: Request clarification or escalate before a write. A plausible match must not become the authorised target.

  3. 03

    Missing or stale evidence

    Check: Exercise absent fields, conflicting sources and evidence outside the agreed freshness boundary.

    Expected response: Expose uncertainty, refuse unsupported conclusions and follow the agreed review path.

  4. 04

    Permitted tool, inappropriate action

    Check: Present a request for which a callable tool would produce the wrong business consequence, even with valid permissions.

    Expected response: Refuse or select an allowed alternative according to the task and policy. Authorisation alone must not count as decision correctness.

  5. 05

    Timeout after a write

    Check: Interrupt the response after the source system may have committed the change.

    Expected response: Reconcile the original command and source state before considering a retry. Do not turn an unknown result into a second business action.

  6. 06

    Model, prompt, tool or knowledge change

    Check: Compare the proposed version with the accepted baseline on relevant normal, exceptional and harmful cases.

    Expected response: Record regressions by consequence. A critical failure remains a release blocker even if the aggregate pass rate improves.

Agree the release decision and its owners. Business owners define acceptable outcomes and exceptions; technical and security owners define execution and control requirements. Agree the evidence, repeat runs where variability matters, and keep critical release blockers separate from residual risks that an accountable owner may accept. Use deterministic checks and source-system confirmation where available; a model-based grader alone is insufficient for a consequential business outcome.

Apply these acceptance and regression scenarios to an agent build

Illustrative architecture scenario, not a customer case.

Follow one CRM change from request to confirmed outcome.

A salesperson asks an agent to record the agreed next step on an opportunity they own. This example assumes that the organisation requires human review before that field changes. It describes a proposed control design, not a deployed customer system.

  1. 01

    Resolve the user and record

    The host establishes the signed-in user. The server derives principal and tenant from verified identity, resolves the opportunity to a stable CRM identifier and checks that the caller may access that object. A record name supplied in a prompt is not sufficient authority.

  2. 02

    Expose one bounded operation

    Select a named capability such as set_opportunity_next_step with a constrained schema. Limit it to the permitted field and authorised records. Use a separate downstream credential scoped to the CRM; a token for the MCP server is not forwarded to the business API.

  3. 03

    Check the proposed decision

    Compare the opportunity, proposed text and supporting call notes with the requested task and current CRM state. If the target is ambiguous or evidence is stale, ask for clarification or escalate before preparing a write.

  4. 04

    Approve this exact change

    Under the policy assumed here, show the opportunity identifier, current value, proposed next step and evidence to the authorised reviewer. Bind approval to the principal, environment, capability version and material parameters. Changed parameters require a new decision.

  5. 05

    Persist a command before execution

    Record a stable command ID, request digest, approval and expected source-record version in durable storage. Validate the request again before the write and use supported CRM concurrency controls. Any permitted retry must retain the original command identity.

  6. 06

    Reconcile an uncertain response

    If the CRM commits the update but the response times out, report an unknown outcome. Look up the original command and its source confirmation before retrying. If the outcome cannot be established, hold further writes and escalate to the system owner.

  7. 07

    Confirm the business result

    Check the source acknowledgement, record identifier, resulting value and revision against the authorised change. Distinguish confirmed completion, rejection, conflict and unresolved state. Sending a request is not confirmation that the opportunity has the intended next step.

  8. 08

    Retain the decision evidence

    Link the trace, verified identities, policy decision, tool version, approval, command ID and source result. Record the outcome and any escalation with access, redaction and retention rules appropriate to the data.

Rejected alternative: retry the write as a new command. A timeout does not establish that the first change failed. Issuing another write can repeat a side effect or overwrite a later change. Reconcile the original operation first; keep an unresolved outcome visible to the accountable owner.

Handover boundary

A server is not finished until another person can operate it.

  • Latency or timeout SLO breachIdentify the slow hop from traces, reduce admission at the affected capability, stop automatic write retries, verify downstream health and communicate any accepted-but-incomplete work.Evidence: Trace sample, queue depth, downstream status and command-state reconciliation.
  • Unexpected tool or schema changeMark the affected capability restricted in the catalogue, then disable execution through the applicable host, gateway, server or runtime policy. Preserve the observed definition, compare it with the approved fingerprint and re-enable only after owner review.Evidence: Definition diff, publisher/version record and approval decision.
  • Suspected token or credential exposureRevoke the affected credential, block the audience or client as appropriate, inspect access and downstream logs, rotate dependent secrets and test that old credentials fail.Evidence: Revocation record, affected principals, access timeline and validation test.
  • Cross-tenant or excessive-data exposureFail closed for the affected server, isolate relevant caches, preserve audit evidence, determine impacted principals and data, correct authorisation or cache partitioning and run cross-tenant regression tests.Evidence: Cache keys, policy decisions, access records and repaired test results.
  • Downstream mutation outcome is uncertainDo not issue a new business command until the original command ID has been reconciled. Query the system of record, classify completed, rejected or unknown work and compensate only through an approved business procedure.Evidence: Command log, system-of-record state and compensation approval.
  • Protocol incompatibility after client or server releaseCapture the negotiated version and error, compare modern and legacy lifecycle behaviour, roll back the affected component or route compatible clients separately, then add the case to the conformance suite.Evidence: Wire capture, version matrix and regression test.

Advanced: cache with an authorisation context

Freshness and permission are separate decisions.

The current protocol defines cache hints for discovery, list operations and resource reads. It does not make arbitrary tool execution safely cacheable.

SurfaceCache positionWhy
server/discoverCacheable with ttlMs and public or private cacheScope.The current caching model explicitly includes discovery results. Capabilities may still differ by deployment or authorisation context.
tools/listCacheable. Use public only when the same catalogue is safe for every caller.The protocol requires cache hints and recommends deterministic tool ordering. Authorisation may change the visible tool set.
prompts/listCacheable with a scope matching the caller-specific catalogue.Prompt lists are included in the protocol cache model and may vary by authorisation.
resources/list and resources/templates/listCacheable per page with consistent cacheScope across one paginated list.Pages are independently fresh; there is no cross-page snapshot guarantee.
resources/readCacheable only with a TTL and scope appropriate to the resource and identity.A private resource result must not be reused across authorisation contexts. A change notification can invalidate a still-fresh result only when the client supports, subscribes to and receives it; otherwise the client must rely on TTL expiry or an explicit refetch.
tools/callNot cacheable through the MCP protocol cache contract.tools/call is absent from the defined cacheable operations. Any application-level memoisation needs explicit semantic, identity, freshness and side-effect rules.
input_required and MRTR retriesDo not cache.The specification excludes interim results and retries carrying inputResponses or requestState from caching.

Commercial route

Apply the production model to one MCP capability.

We review one proposed or existing capability or connector across its contract, identity, side effects, state, caching, failure recovery, observability and ownership. The output is a prioritised production-readiness decision and control plan.

Scope one production MCP capabilityExplore the complete MCP architecture

Primary sources

Protocol claims are grounded in official sources.

The source list distinguishes core protocol requirements, optional extensions and external implementation guidance. The surrounding enterprise control model is a TechOne architecture recommendation.

  1. MCP specificationNormative protocol baseline
  2. MCP specification release notesRelease changes and migration context
  3. ArchitectureStateless host, client and server model
  4. Transport overviewTransport-independent behaviour
  5. Streamable HTTPHTTP requests, headers, streaming and cancellation
  6. stdioLocal process transport and lifecycle
  7. ToolsSchemas, results, errors, state handles and security
  8. ResourcesResource discovery, reads and subscriptions
  9. CachingTTL, cache scope, invalidation and pagination
  10. Tasks extension specificationStable optional, capability-negotiated extension for durable long-running operations
  11. MCP servers and deferred tool loadingClient integration, deferred loading and safety

Direct answers

Questions that expose the hidden architecture decision.

Does stateless MCP mean the application has no state?

No. The current MCP specification has no protocol-level sessions. An application may still keep carts, jobs, browser contexts or transactions, but it should expose an explicit handle and validate the caller on every use.

Which MCP responses can be cached?

The current protocol cache model covers server discovery, tool, prompt and resource lists, resource-template lists and resource reads. It does not make tools/call results generally cacheable.

Can we mark every catalogue response public to improve performance?

Only if the response is identical and safe for every caller. A public result may be shared across authorisation contexts. If identity or scopes affect visibility, use private caching and partition it correctly.

Should one MCP server expose every enterprise API?

Usually not. A smaller, task-relevant capability surface reduces model context, policy complexity, unintended authority and the blast radius of a compromised server. The right boundary follows ownership and trust, not an arbitrary tool count.

Does MCP guarantee idempotent writes?

No general business idempotency guarantee is provided by the protocol. Consequential tools should define a command identifier, duplicate behaviour and a way to retrieve the original outcome.

When should we use stdio rather than Streamable HTTP?

Use stdio for a deliberate local child-process integration with a controlled executable and local isolation. Use Streamable HTTP for a shared remote service that needs ordinary network, identity, gateway and horizontal-scaling controls.

Are Tasks required for long-running work?

No. Tasks is a stable optional MCP extension whose capability support must be negotiated and tested. Where it is unavailable, use an explicit durable job contract with status, cancellation and expiry semantics.

What proves that an MCP server is production-ready?

A successful tool invocation proves connectivity, not production readiness. Evidence should cover contract validation, authorisation, tenancy isolation, side-effect idempotency, failure recovery, protocol compatibility, observable SLOs, change control and an exercised runbook.