Quickstart: MCP server

This guide connects an MCP client to the PDF As You Go server and runs your first operation. The whole exchange — quote, payment, and result — happens inside a single tool call.

Private preview

PDF As You Go is in private preview. Endpoints, retention windows, and supported networks may change. Access is granted on request — see Request preview access.

Before you start

• Preview access. You’ll need the MCP endpoint confirmed for your account — see Request preview access.
• An x402-capable MCP client. The client must be able to answer a 402 challenge with a signed payment. See Paying with x402 for what that means in practice.
• A funded wallet. USDC on a supported network (Base is the default). Each operation costs $0.05.

1. Add the server to your client.

   Point your MCP client at the remote server and give it a wallet so it can pay. The exact config keys vary by client; a representative mcpServers entry looks like this:

   MCP client config (representative)

   {
     "mcpServers": {
       "pdf-as-you-go": {
         "url": "https://mcp.pdfasyougo.com",
         "x402": {
           "network": "base",
           "wallet": "${X402_WALLET_PRIVATE_KEY}"
         }
       }
     }
   }

   For per-client instructions (Claude Desktop, Cursor, and stdio-only clients via a connector), see Connecting a client.

2. Restart the client and confirm the tools appear.

   You should see the PDF tools — merge_pdfs, add_text_watermark, extract_pages, and the rest. The full list is in the Tools reference.

3. Ask the agent to do something.

   In plain language:

   Merge https://example.com/a.pdf and https://example.com/b.pdf, then add a “CONFIDENTIAL” watermark to every page.

   The agent will call merge_pdfs and then add_text_watermark — two operations, $0.10 total.

4. Payment happens transparently.

   Each tool call returns a 402 the first time; your x402-capable client signs the payment and retries automatically. You don’t approve anything per call unless your client is configured to.

5. Get the result.

   Each tool returns a short-lived download URL for the output PDF. URLs expire after the retention window (preview default: 60 minutes), so fetch or hand off the file promptly.

What a tool call looks like

Under the hood, the merge_pdfs call the agent makes carries arguments like:

{
  "files": [
    "https://example.com/a.pdf",
    "https://example.com/b.pdf"
  ]
}

and returns:

{
  "output": {
    "url": "https://files.pdfasyougo.com/o/3f9a…?token=…",
    "expires_at": "2026-06-29T12:00:00Z",
    "pages": 24,
    "bytes": 184320
  },
  "operation": "merge_pdfs",
  "cost": "0.05 USDC"
}

Tip

Prefer passing documents by URL (or uploading them) rather than pasting base64 into the conversation — it keeps large files out of your model’s context window. See File handling.

Next

• Connecting a client — Claude Desktop, Cursor, and connector setups.
• Paying with x402 — how the client settles each call.
• Tools — every tool and its parameters.