feat: add McpClient wrapper for MCP client transport parity

[brendanjryan]

Summary

Adds McpClient, a payment-aware MCP client wrapper that brings Python to parity with the TypeScript McpClient.wrap API on the SDK features table.

What it does

McpClient wraps an MCP SDK ClientSession and overrides call_tool with automatic payment handling:

1. Calls the tool normally
2. If the server returns -32042 (Payment Required), parses the challenges
3. Matches the challenge to an installed payment method by name + intent
4. Creates a credential and retries the call with it in _meta
5. Extracts the receipt from the result's _meta

Usage

from mcp import ClientSession
from mcp.client.sse import sse_client
from mpp.extensions.mcp import McpClient
from mpp.methods.tempo import tempo, TempoAccount, ChargeIntent

account = TempoAccount.from_key('0x...')
method = tempo(account=account, intents={'charge': ChargeIntent()})

async with sse_client(url) as streams:
    async with ClientSession(streams[0], streams[1]) as session:
        await session.initialize()
        client = McpClient(session, methods=[method])
        result = await client.call_tool('premium_tool', {'query': 'hello'})
        print(result.receipt)

[chatgpt-codex-connector]

💡 Codex Review

pympp/src/mpp/methods/tempo/intents.py

Lines 242 to 245 in 6cd584c

	if self._store is not None:
	store_key = f"mpp:charge:{payload.hash.lower()}"
	if not await self._store.put_if_absent(store_key, payload.hash):
	raise VerificationError("Transaction hash already used")

Don't consume tx hashes before verification succeeds

With replay protection enabled, this marks the hash as used before any RPC or log checks run. If eth_getTransactionReceipt is temporarily unavailable, the transaction is still pending, or verification fails for any transient reason, the key is never cleared and every later retry will raise Transaction hash already used. That permanently rejects legitimate payments after recoverable failures whenever a store is configured.

---

pympp/src/mpp/store.py

Lines 18 to 22 in 6cd584c

	async def put_if_absent(self, key: str, value: Any) -> bool:
	"""Store *value* under *key* only if *key* does not already exist.
	Returns ``True`` if the key was new and the write succeeded,
	``False`` if the key already existed (duplicate).

Preserve compatibility with existing Store implementations

ChargeIntent accepts any exported Store, but this change makes put_if_absent() a new required method. Existing Redis/Dynamo/custom stores built against the previously published get/put/delete interface will now fail at runtime with AttributeError the first time hash replay protection is exercised, so this is a breaking change for current integrations rather than an internal refactor.

---

pympp/src/mpp/extensions/mcp/client.py

Lines 109 to 113 in 6cd584c

	name: str,
	arguments: dict[str, Any] | None = None,
	*,
	timeout: float | None = None,
	meta: dict[str, Any] | None = None,

Forward progress callbacks through the MCP wrapper

ClientSession.call_tool() supports a progress_callback for long-running tools, but the wrapper drops that parameter entirely. Any caller migrating from session.call_tool(...) to McpClient.call_tool(...) can no longer pass the callback, so paid tools lose progress notifications (or the caller gets a TypeError if they keep the old call shape).

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[tempoxyz-bot]

👁️ Cyclops Review

This PR adds McpClient, a payment-aware wrapper around MCP ClientSession that automatically handles -32042 payment challenges. The implementation is clean and well-tested for the happy path, but has a meaningful input validation gap at the trust boundary with untrusted MCP servers and a return-type compatibility issue with the standard MCP SDK.

Reviewer Callouts

• ⚡ Challenge Trust Boundary: -32042 error data originates from remote MCP servers and should be treated as adversarial input. All field access should be guarded.
• ⚡ Dependency Drift: Upstream modelcontextprotocol/python-sdk mainline has renamed McpError to MCPError. Not exploitable today, but a future integration break risk.
• ⚡ API Surface Parity: The TypeScript McpClient.wrap preserves the full client interface; the Python version currently only exposes call_tool. Integrations that pass the client object to frameworks expecting ClientSession methods will fail.

[tempoxyz-bot]

🚨 [SECURITY] Malformed Server Challenges Crash McpClient via Unhandled Exceptions

_is_payment_required_error validates that challenges is a non-empty list but does not validate element types or required fields. _match_challenge then calls .get() on each element, which raises AttributeError if an element is a string instead of a dict. Even when elements are dicts, MCPChallenge.from_dict(cd) raises KeyError if required fields (id, realm, request) are absent, and cd.get("intent") in set(...) raises TypeError for unhashable values. These unhandled exceptions escape call_tool, bypassing standard McpError handlers and crashing caller workflows when connected to a malicious or misconfigured MCP server.

Recommended Fix: Add schema validation before matching: require each entry to be a dict with required string fields (id, realm, method, intent) and a dict request. Skip malformed entries with a warning. Also harden _is_payment_required_error with all(isinstance(c, dict) for c in challenges).

[tempoxyz-bot]

⚠️ [ISSUE] McpToolResult Breaks CallToolResult API Contract

McpClient.call_tool returns McpToolResult(result=..., receipt=...) instead of the standard MCP CallToolResult. Downstream code expecting result.content will crash since .content lives on result.result.content. The wrapper also omits list_tools, read_resource, initialize, and other ClientSession methods, so it cannot be used as a drop-in replacement. The upstream TypeScript McpClient.wrap preserves the original client surface via object spread.

Recommended Fix: Proxy attribute access to the underlying CallToolResult via __getattr__ on McpToolResult, and add __getattr__ on McpClient to delegate unknown methods to _session.

[tempoxyz-bot]

🛡️ [DEFENSE-IN-DEPTH] No Retry State Exposed After Payment Credential Transmission

If the retry request fails due to a network timeout after the credential was already created and sent, call_tool surfaces the transport exception without indicating payment state. Fault-tolerant callers that retry call_tool will trigger a new challenge/credential cycle, potentially resulting in duplicate charges. This matches upstream TypeScript behavior but makes it difficult for SDK consumers to build resilient retry logic.

Recommended Fix: Consider exposing intermediate payment state (e.g., via a custom exception attribute or callback) so callers can distinguish "credential sent but response lost" from "no payment attempted".