Bind one MCP Tool without weakening durability.

Accept one deliberately narrow profile

Transport

Verified HTTPS in production; literal-loopback HTTP only for managed sidecars and tests. Redirects, HTTP retries, sessions, and SSE fail closed.

Discovery

One modern discovery at startup, bounded Tool catalog paging, exact protocol version, required Tools capability, and pinned self-reported server name/version.

Schemas

Remote input/output JSON Schemas must exactly match RFC 8785 canonical bytes in the authoritative local registry. Remote annotations never define local risk or policy.

Results

Complete structured content only, bounded and validated locally. The current profile rejects artifact, image, audio, embedded-resource, and resource-link materialization.

Freeze the binding at readiness

Build the local ToolDescriptor from reviewed configuration. A server upgrade or schema change requires a new binding; runtime calls never rediscover silently.

let adapter = McpRemoteTool::connect(
    local_descriptor,
    "lookup_issue",
    ProviderEndpoint::https("https://mcp.example.com/v1/")?,
    McpServerIdentity::new("issue-service", "2026.09.0")?,
    Arc::new(schema_registry),
    Arc::new(authorization_provider),
    McpHttpOptions::default(),
)
.await?;

TLS authenticates the configured endpoint. The discovered implementation name/version is self-reported metadata: pinning detects drift, but does not replace mTLS or an authenticated gateway when stronger server identity is required.

Resolve secrets per admitted attempt

Multi-tenant deployments should implement McpAuthorizationProvider over vault-backed handles. The adapter waits for its call gate before resolving attempt credentials, redacts authorization from Debug, clears the slot after exchange, and never copies credentials into MCP metadata. Static bearer authorization is intended only for controlled single-tenant bindings.

Keep a lost write ambiguous

1. Validate locally

   Reject input outside the pinned schema before network dispatch.

2. Call once

   Each admitted durable attempt sends one tools/call.

3. Do not invent success

   If a locally declared write loses its response, return Unknown external effect, AmbiguousExternalOutcome, and ReconcileFirst.

4. Validate the result

   Accept only complete structured output that passes the pinned local output schema.

Reconcile without calling the Tool again

A trusted worker or operations boundary may convert an exact Unknown physical attempt into a validated result or error. The runtime binds the evidence to the invocation and attempt, validates result JSON against the frozen local schema, and commits a distinct audit event in one fenced PostgreSQL transaction. It never resolves or dispatches the Tool provider.

let reconciliation = ToolReconciliationHandoff::result(
    live_fence,
    unknown_invocation,
    reconciliation_event_id,
    authoritative_result,
)?;

match executor.commit_tool_reconciliation(reconciliation).await? {
    ToolReconciliationOutcome::Committed { .. } => acknowledge(),
    ToolReconciliationOutcome::Idempotent { .. } => acknowledge(),
}

Exact retries are idempotent. A handoff retains its authoritative evidence across persistence failures and can be rebound only to a new live fence for the same run.

Record a confirmed failure without resending the write

The privileged stateknot_reconcile_tool_error_v1 operations Tool requires its own stateknot:reconcile-error scope and current resource/evidence authorization. It accepts only confirmed not_applied or applied effects for the exact original Unknown attempt and atomically records Failed with an authorization audit. Unknown or partial effects remain unresolved.

The host fixes RetryAdvice::Never. Not applied does not mean execution never started, no charges, or safe retry. Lost responses recover the same receipt from the identical request; success/failure races have one winner. The existing success-result Tool and its scope remain separate. This does not settle provider charges or complete production acceptance.

Follow the failure reconciliation integration and incident guide for host registration, closed request fields, evidence verification and PostgreSQL 16/17 qualification.

Know what this profile rejects

• Stateful sessions, SSE, legacy initialization, and reconnect.
• MRTR, Tasks, incomplete results, progress, and artifact content.
• Tools requiring StateKnot idempotency-key injection; generic MCP has no safe standard carrier for that durable key.
• Server behavior, Resource/Prompt clients, roots, sampling, elicitation, logging, and MCP Apps. The separate Server profile does not broaden this strict Remote Tool contract.

Run the profile and durable contracts

cargo test -p stateknot-integrations --test mcp_contract --locked
cargo test -p stateknot-integrations --test mcp_durable --locked -- --test-threads=1

The suite proves discovery order, identity/schema pinning, credential headers, annotation distrust, pre-registration drift rejection, and ambiguous lost writes. The PostgreSQL 16/17 matrix additionally proves durable-before-dispatch state, a lost write response, Unknown, duplicate suppression, authoritative reconciliation, and one physical network call. Read the full profile and operations contract and the frozen MCP conformance status. StateKnot does not claim complete official MCP client or server conformance.