diff --git a/src/pages.gen.ts b/src/pages.gen.ts index a768a63e..0bc6c87d 100644 --- a/src/pages.gen.ts +++ b/src/pages.gen.ts @@ -43,6 +43,9 @@ 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/mcp-sdk'; 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..a0ba5d22 --- /dev/null +++ b/src/pages/partner-integrations/cloudflare-agents.mdx @@ -0,0 +1,94 @@ +--- +description: "Use MPP with the Cloudflare Agents SDK." +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 + +Add 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.addMcpServer('premium-search', '') + 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 setup. + +```ts [agent.ts] +const method = tempo({ + account: provider.getAccount(), + ...provider.getMppxParameters({ accessKey }), +}) + +// Use the method for paid MCP tool calls. +McpClient.wrap(this.mcp.mcpConnections[id].client, { + methods: [method], +}) + +// Use the same method for payment-aware fetch calls. +Mppx.create({ + methods: [method], +}) +``` + +See [Managing agent spend](/guides/managing-agent-spend) for limits, scopes, recipients, and revocation. diff --git a/src/pages/partner-integrations/mcp-sdk.mdx b/src/pages/partner-integrations/mcp-sdk.mdx new file mode 100644 index 00000000..d6dac8b6 --- /dev/null +++ b/src/pages/partner-integrations/mcp-sdk.mdx @@ -0,0 +1,78 @@ +--- +description: "Use MPP with the official TypeScript MCP SDK." +--- + +# Official MCP SDK + +Use [`Mppx.create`](/sdk/typescript/client/Mppx.create) to let the [official TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) 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 payment-aware fetch wrapper creates a Credential, retries the call, and returns the result. + +```bash [terminal] +$ pnpm add mppx viem @modelcontextprotocol/sdk +``` + +```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 Streamable HTTP transport uses the payment-aware fetch for both free and paid tool calls. + +```ts [client.ts] +import { Client } from '@modelcontextprotocol/sdk/client/index.js' +import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js' +import './payments' + +const client = new Client({ + name: 'mpp-app', + version: '1.0.0', +}) + +await client.connect(new StreamableHTTPClientTransport(new URL(''))) + +const result = await client.callTool({ + name: 'premium_search', + arguments: { query: 'tempo' }, +}) + +console.log(result) +``` + +## Pay for HTTP requests + +Call `Mppx.create` before making 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 [client.ts] +import './payments' + +export async function paidPing() { + const response = await fetch('https://mpp.dev/api/ping/paid') + return response.json() +} +``` + +## 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 setup. + +```ts [payments.ts] +Mppx.create({ + methods: [ + tempo({ + account: provider.getAccount(), + ...provider.getMppxParameters({ accessKey }), + }), + ], +}) +``` + +See [Managing agent spend](/guides/managing-agent-spend) for limits, scopes, recipients, and revocation. 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..24804245 --- /dev/null +++ b/src/pages/partner-integrations/vercel-ai-sdk.mdx @@ -0,0 +1,98 @@ +--- +description: "Use MPP with the Vercel AI SDK." +--- + +# 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 setup. + +```ts [payments.ts] +Mppx.create({ + methods: [ + tempo({ + account: provider.getAccount(), + ...provider.getMppxParameters({ accessKey }), + }), + ], +}) +``` + +See [Managing agent spend](/guides/managing-agent-spend) for limits, scopes, recipients, and revocation. diff --git a/vocs.config.ts b/vocs.config.ts index 409feb08..45542d1b 100644 --- a/vocs.config.ts +++ b/vocs.config.ts @@ -288,6 +288,23 @@ export default defineConfig({ { text: "Use with your app", link: "/quickstart/client" }, ], }, + { + text: "Partner Integrations", + items: [ + { + text: "Cloudflare Agents", + link: "/partner-integrations/cloudflare-agents", + }, + { + text: "Official MCP SDK", + link: "/partner-integrations/mcp-sdk", + }, + { + text: "Vercel AI SDK", + link: "/partner-integrations/vercel-ai-sdk", + }, + ], + }, { text: "Guides", items: [