diff --git a/src/pages.gen.ts b/src/pages.gen.ts index a768a63e..a77cecb1 100644 --- a/src/pages.gen.ts +++ b/src/pages.gen.ts @@ -43,6 +43,8 @@ type Page = | { path: '/intents/subscription'; render: 'static' } | { path: '/mpp-vs-x402'; render: 'static' } | { path: '/overview'; render: 'static' } + | { path: '/partner-integrations/cloudflare-agents'; render: 'static' } + | { path: '/partner-integrations/vercel-ai-sdk'; render: 'static' } | { path: '/payment-methods/card/charge'; render: 'static' } | { path: '/payment-methods/card'; render: 'static' } | { path: '/payment-methods/custom'; render: 'static' } diff --git a/src/pages/partner-integrations/cloudflare-agents.mdx b/src/pages/partner-integrations/cloudflare-agents.mdx new file mode 100644 index 00000000..b6351924 --- /dev/null +++ b/src/pages/partner-integrations/cloudflare-agents.mdx @@ -0,0 +1,75 @@ +--- +description: "Use mppx with Cloudflare Agents, MCP tools, and HTTP requests." +imageDescription: "Connect Cloudflare Agents to paid MPP MCP tools and HTTP APIs" +--- + +# Cloudflare Agents + +Use [`McpClient.wrap`](/sdk/typescript/client/McpClient.wrap) and [`Mppx.create`](/sdk/typescript/client/Mppx.create) to let a [Cloudflare Agent](https://developers.cloudflare.com/agents/) pay for MCP tools and HTTP requests through MPP. Free calls pass through untouched; when a paid tool or a 402-protected request returns an MPP Challenge, the wrapped client creates a Credential, retries the call, and returns the result. + +```bash [terminal] +$ pnpm add agents mppx viem +``` + +```ts [payments.ts] +import { privateKeyToAccount } from 'viem/accounts' + +export const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`) +``` + +:::info +The example uses an environment private key for brevity. For production agents, manage spend with scoped access keys instead of giving the runtime a private key. See [Managing agent spend](/guides/managing-agent-spend). +::: + +## Pay for MCP tools + +Connect the MCP server, then wrap the client stored on the Cloudflare MCP connection. Calls through the wrapped client are payment-aware. + +```ts [agent.ts] +import { Agent } from 'agents' +import { tempo } from 'mppx/client' +import { McpClient } from 'mppx/mcp/client' +import { account } from './payments' + +export class MyAgent extends Agent { + async onStart() { + const { id } = await this.mcp.connect('') + const client = McpClient.wrap(this.mcp.mcpConnections[id].client, { + methods: [tempo({ account })], + }) + + const result = await client.callTool({ + name: 'premium_search', + arguments: { query: 'tempo' }, + }) + + console.log(result) + } +} +``` + +`McpClient.wrap` keeps the Cloudflare MCP connection shape intact. The agent can keep using the same client APIs. + +## Pay for HTTP requests + +Call `Mppx.create` before the agent makes HTTP requests. It installs the payment-aware fetch, so later `fetch` calls in the same runtime can handle free responses, paid MPP responses, and [x402 payment challenges](/guides/use-mpp-with-x402). + +```ts [agent.ts] +import { Mppx, tempo } from 'mppx/client' +import { account } from './payments' + +Mppx.create({ + methods: [tempo({ account })], +}) + +export async function paidPing() { + const response = await fetch('https://mpp.dev/api/ping/paid') + return response.json() +} +``` + +## Manage agent spend + +The examples above use a standard viem account. For long-running apps or agents, use scoped access keys when the runtime should pay in the background with spending limits, call scopes, recipient restrictions, and independent revocation. + +Create the access key first, then pass the Tempo account into the same `tempo({ account })` setup. See [Managing agent spend](/guides/managing-agent-spend). diff --git a/src/pages/partner-integrations/vercel-ai-sdk.mdx b/src/pages/partner-integrations/vercel-ai-sdk.mdx new file mode 100644 index 00000000..b4c0b348 --- /dev/null +++ b/src/pages/partner-integrations/vercel-ai-sdk.mdx @@ -0,0 +1,82 @@ +--- +description: "Use mppx with Vercel AI SDK agents, tools, and MCP clients." +--- + +# Vercel AI SDK + +Use [`Mppx.create`](/sdk/typescript/client/Mppx.create) to let a [Vercel AI SDK agent](https://ai-sdk.dev/docs/agents/overview) pay for MCP tools and HTTP requests through MPP. Free calls pass through untouched; when a paid tool or a 402-protected request returns an MPP Challenge, the wrapped client creates a Credential, retries the call, and returns the result. + +```bash [terminal] +$ pnpm add mppx viem ai @ai-sdk/mcp zod +``` + +```ts [payments.ts] +import { Mppx, tempo } from 'mppx/client' +import { privateKeyToAccount } from 'viem/accounts' + +const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`) + +Mppx.create({ + methods: [tempo({ account })], +}) +``` + +## Pay for MCP tools + +Create the MCP client after `Mppx.create`. The AI SDK MCP transport uses the payment-aware fetch for both free and paid tool calls. + +```ts [agent.ts] +import { createMCPClient } from '@ai-sdk/mcp' +import { generateText } from 'ai' +import { yourProvider } from 'your-custom-provider' + +const mcp = await createMCPClient({ + transport: { type: 'http', url: '' }, +}) + +const { toolResults } = await generateText({ + model: yourProvider('your-model-id'), + prompt: 'Call the MCP tool.', + tools: await mcp.tools(), + toolChoice: 'required', +}) + +console.log(toolResults) +await mcp.close() +``` + +## Pay for HTTP requests + +Define a normal AI SDK tool and call `fetch` inside `execute`. Because `Mppx.create` ran first, the HTTP request is payment-aware. + +```ts [agent.ts] +import { generateText, tool } from 'ai' +import { yourProvider } from 'your-custom-provider' +import { z } from 'zod' + +const { toolResults } = await generateText({ + model: yourProvider('your-model-id'), + prompt: 'Call paidPing.', + tools: { + paidPing: tool({ + description: 'Call a paid MPP HTTP endpoint.', + inputSchema: z.object({}), + execute: async () => { + const response = await fetch('https://mpp.dev/api/ping/paid') + return response.json() + }, + }), + }, + toolChoice: { type: 'tool', toolName: 'paidPing' }, +}) + +console.log(toolResults) +``` + +The `tempo({ account })` helper used above supports Tempo [charge](/payment-methods/tempo/charge) and [session](/payment-methods/tempo/session) challenges. + +## Manage agent spend + +The example above uses a standard viem account. For long-running apps or agents, use scoped access keys when the runtime should pay in the background with spending limits, call scopes, recipient restrictions, and independent revocation. + +Create the access key first, then pass the Tempo account into the same `Mppx.create` setup. See [Managing agent spend](/guides/managing-agent-spend). diff --git a/vocs.config.ts b/vocs.config.ts index 409feb08..5d32e3c3 100644 --- a/vocs.config.ts +++ b/vocs.config.ts @@ -60,6 +60,18 @@ export default defineConfig({ source: "/guides/upgrade-x402", destination: "/guides/use-mpp-with-x402", }, + { + source: "/agent-sdks/cloudflare-agents", + destination: "/partner-integrations/cloudflare-agents", + }, + { + source: "/agent-sdks/vercel-ai-sdk", + destination: "/partner-integrations/vercel-ai-sdk", + }, + { + source: "/partner-sdks/cloudflare-agents", + destination: "/partner-integrations/cloudflare-agents", + }, { source: "/challenges", destination: "/protocol/challenges" }, { source: "/challenge", destination: "/protocol/challenges" }, { source: "/credentials", destination: "/protocol/credentials" }, @@ -288,6 +300,19 @@ export default defineConfig({ { text: "Use with your app", link: "/quickstart/client" }, ], }, + { + text: "Partner Integrations", + items: [ + { + text: "Cloudflare Agents", + link: "/partner-integrations/cloudflare-agents", + }, + { + text: "Vercel AI SDK", + link: "/partner-integrations/vercel-ai-sdk", + }, + ], + }, { text: "Guides", items: [