`McpClient.wrap`

Payment-aware MCP client

Choose a signing account

Create a server-only wallet.ts module, then import account wherever an example creates a local signing account.

wallet.ts

import { privateKeyToAccount } from 'viem/accounts'

export const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)

Wraps an MCP SDK client with automatic payment handling. When a tool call returns a -32042 payment required error, the wrapper creates a Credential and retries the call.

Usage

With call options

Pass context and timeout through the second argument to callTool.

const result = await mcp.callTool(
  { name: 'premium_tool', arguments: { query: 'hello' } },
  { context: { foo: 'bar' }, timeout: 30_000 },
)

Return type

McpClient.wrap returns an object that spreads the original client and overrides callTool with a payment-aware version.

type McpClient<client, methods> = Omit<client, 'callTool'> & {
  callTool: (
    params: {
      arguments?: Record<string, unknown>
      name: string
      _meta?: Record<string, unknown>
    },
    options?: CallToolOptions<methods>,
  ) => Promise<CallToolResult>
}

The CallToolResult type extends the SDK's return type with a receipt field:

type CallToolResult = Awaited<ReturnType<Client['callTool']>> & {
  receipt: Mcp.Receipt | undefined
}

Parameters

client

Type: Pick<Client, 'callTool'>

The MCP SDK client instance to wrap. Must have a callTool method—typically an instance of Client from @modelcontextprotocol/sdk/client.

config.methods

Type: readonly Method.AnyClient[]

Array of payment methods to use when handling payment Challenges. The wrapper matches Challenges from the server against installed methods by name and intent.

Suggest changes to this page