Overview

The AgentPMT MCP Router is a universal MCP server that enables your AI agents to connect to the real world, including sending and receiving payments and accessing our ecosystem of pay per call services. Install once with npm, configure automatically with our wizard, and start using powerful AI tools instantly.

________________________________________________________________________

Prefer To Watch The Tutorial?

________________________________________________________________________

Auto Installer

The auto installer sets up the config files for these platforms

✅ Claude Desktop — Anthropic's desktop app

✅ Claude Code CLI — Anthropic's CLI tool

✅ Cursor — AI-first code editor

✅ VS Code — With GitHub Copilot

✅ Windsurf — Codeium's AI editor

✅ Zed — High-performance code editor

✅ OpenAI Codex CLI — OpenAI's CLI tool

✅ Google Gemini CLI — Google's CLI tool

For any other MCP compatible agent system, you will need to edit the config file directly. Some examples are shown below.

Prerequisites

Before installing the MCP server, you need:

1. Node.js and npm

The MCP router is distributed as an npm package, so you need Node.js installed.

Check if you already have it:

Open your terminal (Command Prompt on Windows, Terminal on macOS/Linux) and run:

If you see a version number (like 10.2.3), you're ready to go!

If not installed:

Download from https://nodejs.org (choose the LTS version)

Install it following the installer instructions

Works on Windows, macOS, and Linux

After installation, restart your terminal and verify with npm --version

2. AgentPMT Account Credentials

You'll need two keys from your AgentPMT dashboard:

API Key:

Dashboard → Account Details → API Key → Generate API Key

(Your wallet must be activated for this to work)

Budget Key:

Dashboard → AI Budgets → Select budget → Generate AI Key

3. Supported AI Tool Installed

At least one of: Claude Desktop, Claude Code CLI, Cursor, VS Code, Windsurf, Zed, OpenAI Codex CLI, or Google Gemini CLI

Quick Installation (3 Steps)

Step 1: Install the MCP Router

Open your terminal and run:

What this does:

Downloads the universal MCP server package

Automatically detects your operating system (Windows/macOS/Linux)

Downloads the appropriate router binary from GitHub

Makes the agentpmt-install command available system-wide

Step 2: Run the Setup Wizard

After installation completes, run the configuration wizard:

The wizard will:

1. Automatically detect all installed AI tools on your system

2. Prompt for Server Name (default: "agentpmt")

3. Ask for your API Key (from AgentPMT dashboard)

4. Ask for your Budget Key (from AgentPMT dashboard)

5. Automatically configure ALL detected platforms

Step 3: Restart Your AI Tools

After configuration completes:

Close and restart your AI tool(s)

The AgentPMT tools will appear in your tool list

Note: Some platforms (like Claude Desktop) may require 2-3 restarts to load MCP servers

Verify Installation

Open your AI tool and check if AgentPMT tools appear in the available tools list. If tools don't appear, see the Troubleshooting section below.

Manual Configuration

When to Configure Manually

Use manual configuration if:

The automatic wizard didn't detect your AI tool

You want to use different keys for different tools

You need custom configuration settings

You're using a platform not supported by the wizard yet

How Manual Configuration Works

Each AI platform stores its MCP configuration in a JSON or TOML file. You'll need to:

1. Find the configuration file for your platform (see locations below)

2. Open it in a text editor

3. Add the AgentPMT configuration

4. Save the file

5. Restart your AI tool

Configuration Examples by Platform -

Claude Desktop

Config file location:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

Claude Code CLI

Config file: ~/.claude.json (all platforms)

Cursor

Config file: ~/.cursor/mcp.json (all platforms)

After adding: Open Cursor Settings → Features → MCP and click Refresh

VS Code

Config file location:

Windows: %APPDATA%\Code\User\mcp.json

macOS: ~/Library/Application Support/Code/User/mcp.json

Linux: ~/.config/Code/User/mcp.json

Windsurf

Config file: ~/.codeium/windsurf/mcp_config.json (all platforms)

Zed

Config file location:

Windows: %APPDATA%\Zed\settings.json

macOS/Linux: ~/.config/zed/settings.json

After adding: Check Agent Panel → Server Extensions for a green indicator

OpenAI Codex CLI

Config file: ~/.codex/config.toml (all platforms)

Google Gemini CLI

Config file: ~/.gemini/settings.json (all platforms)

Important Configuration Notes

Replace placeholders:

YOUR_API_KEY - Your actual API key from AgentPMT dashboard

YOUR_BUDGET_KEY - Your actual Budget key from AgentPMT dashboard

YOUR_PLATFORM - Replace with: windows, darwin (macOS), or linux

Understanding file paths:

On macOS/Linux: ~ means your home directory (e.g., /Users/yourname)

On Windows: %APPDATA% is typically C:\Users\YourUsername\AppData\Roaming

Auto-Updates

The MCP router automatically updates to the latest version on every startup using the @latest tag. This ensures you always have access to the newest features and bug fixes.

Startup behavior:

First run: Downloads and caches latest version (~2-3 seconds)

Subsequent runs: Checks for updates and downloads if available (~1-3 seconds)

To disable auto-updates:

Modify your config to use a specific version instead of @latest:

Troubleshooting

Installation Issues

"npm: command not found" or "npm is not recognized"

You need to install Node.js first: https://nodejs.org

After installing, restart your terminal/command prompt

Verify with: npm --version

Permission denied / EACCES errors (macOS/Linux)

Try: sudo npm install -g @agentpmt/mcp-router

Or configure npm to install globally without sudo: npm permissions guide

Windows Defender / SmartScreen warnings

This is normal for new applications

Click "More info" then "Run anyway" to proceed

Tools Not Appearing in Your AI Platform

First steps to try:

1. Restart your AI tool completely (close and reopen the application)
2. Some tools (especially Claude Desktop) need 2-3 complete restarts
3. Verify your API Key and Budget Key are correct (no extra spaces)
4. Check that your Budget Key is active (not paused) in your dashboard
5. Confirm you've added tools to your budget

Check the logs:

Claude Desktop logs:

Windows: %APPDATA%\Claude\logs\mcp.log

macOS: ~/Library/Application Support/Claude/logs/mcp.log

Linux: ~/.config/Claude/logs/mcp.log

Look for errors mentioning "agentpmt" to diagnose the issue

Authorization / Permission Errors

401 or 403 errors

Double-check both your API Key and Budget Key

Copy keys directly from dashboard (avoid typing manually)

Ensure your Budget Key is not paused

Verify your budget has tools approved

Confirm your wallet is activated and funded

Purchase / Spending Issues

Tool calls fail with "insufficient funds"

Check wallet balance in your dashboard

Verify your budget limit hasn't been exceeded

For paid tools, confirm they're approved on your budget

Try adding funds or increasing your budget limit

Platform-Specific Issues

Cursor: "MCP server failed to start"

Open Cursor Settings → Features → MCP

Click "Refresh" to reload servers

Check that ~/.cursor/mcp.json has correct JSON format

Verify no trailing commas in the JSON

Zed: Green indicator doesn't appear

Check Agent Panel → Server Extensions

Verify ~/.config/zed/settings.json format is correct

Restart Zed completely

VS Code: GitHub Copilot doesn't see tools

Ensure GitHub Copilot extension is installed and active

Check that MCP configuration is in correct location for your OS

Restart VS Code after config changes

Claude Desktop: Still not loading after restarts

Try 2-3 complete restarts (fully quit and reopen)

Check the mcp.log file for specific errors

Verify the config file location is correct for your OS

Make sure the config file has valid JSON format

Still Having Issues?

Check the MCP logs for specific error messages

Visit our documentation: https://agentpmt.com/docs

Send us a message on Discord: Tech Support

Advanced Topics

Multiple Budgets

You can create separate configurations for different budgets or use cases:

1. Add multiple entries with different names (e.g., "agentpmt-research", "agentpmt-production")
2. Use different Budget Keys for each
3. Each will show as a separate server in your AI tool

Example:

Uninstalling

To remove the MCP router:

Then manually remove the "agentpmt" entry from your AI tool's configuration file.

Support Resources

📖 Documentation: https://agentpmt.com/docs

🐛 Issues: https://github.com/Apoth3osis-ai/agent-payment-mcp/issues

🌐 Website: https://agentpmt.com

📦 npm Package: https://www.npmjs.com/package/@agentpmt/mcp-router

Send API calls to tools directly

Sometimes it is helpful during prompt engineering to see exactly what your agent will see when they try to use a tool. Maybe you want to incorporate a tool or data source into a hardcoded workflow you are building. Or maybe your agent just works better with API calls instead of an MCP tool connection. Whatever the reason, you can access AgentPMT in the same way that you would make any other API call.

Prerequisites:

API Key: Dashboard → Account Details → API Key → Generate.

Budget Key: Dashboard → AI Budgets → select budget → Generate AI Key.

Base URL

https://api.agentpmt.com

Authentication

In every request, always include your keys in the headers like this:

X-API-KEY: YOUR_API_KEY

X-BUDGET-KEY: YOUR_BUDGET_KEY

Note: Header names are case-insensitive, but we recommend using uppercase for consistency.

Available Endpoints

List Tools Available on Your Budget

Endpoint: GET /products/fetch

Optional URL parameters:

page=1

page_size=10 (max 100)

Product fetch requests are paginated with a max size of 100 per page.

cURL Example:

Response Example:

Response Field Definitions

x-prepaid-balance: Shows the current number of prepaid tool calls available on that tool. When "uses_remaining" reaches 0, the next call will trigger a new purchase of the minimum order size.

x-pricing: Outlines the pricing structure for the tool:

metering: "prepaid" means you buy uses in advance

price_per_unit: Cost per single use in USDC

minimum_order_size: Minimum number of uses you must purchase at once

minimum_order_price: Total cost of minimum order (minimum_order_size × price_per_unit)

pagination: Tells you if you should make another call to fetch the next page of tools

Use a Tool (Purchase/Execute)

Endpoint: POST /products/purchase

cURL Example:

Response Example:

Purchase Response Fields

purchase_result: Indicates what happened with this request:

used_existing_access_token: Used prepaid access you already own

new_order_placed: Purchased new access (minimum order)

free_tool: Tool is free, no payment required

purchase_details: If a new order was placed, contains transaction details:

Order ID

Amount paid in USDC

Number of uses purchased

Blockchain transaction hash

See the Access Tokens & Orders documentation for detailed information on how purchases work.

Standard Response Format

All API responses follow this structure:

Troubleshooting

Authentication Errors

401 Unauthorized or 403 Forbidden:

Double-check both X-API-KEY and X-BUDGET-KEY headers

Ensure keys are copied correctly (no extra spaces)

Verify Budget Key is not paused in your dashboard

Confirm the Budget Key matches the API Key (same user account)

Tool Access Errors

Tool not found or unauthorized:

Confirm the tool is live (published, not draft)

Verify the tool is added to your budget

Check that your budget is not paused

Payment Errors

Insufficient funds:

Check your wallet balance in the dashboard

Ensure your budget limit hasn't been exceeded

For paid tools, the minimum order amount must be available

Fund your wallet or increase budget limits, then retry

Payment authorization failed:

Verify your wallet is activated

Ensure you've approved USDC spending via the smart contract

Check that the smart contract authorization is not paused

Request Validation Errors

400 Bad Request:

Match the tool's parameter schema exactly (correct types and required fields)

Check parameter names for typos

Ensure JSON formatting is valid

Verify all required parameters are included

Rate Limits

API requests are subject to reasonable rate limits to ensure platform stability. If you exceed rate limits, you'll receive a 429 Too Many Requests response. Wait a moment and retry.

Best Practices

1. Check prepaid balance: Before making calls, check x-prepaid-balance to see if you have remaining uses
2. Handle purchases gracefully: When purchase_result indicates a new order, log the transaction details
3. Monitor budget limits: Track your spending in the dashboard to avoid hitting budget caps
4. Error handling: Implement retry logic for transient errors, but not for authentication failures
5. Secure your keys: Never expose API keys or Budget keys in client-side code or public repositories

Directly connecting your Agent Payment MCP server to Postman allows you to test your integrated tools and verify data responses before building complex agent prompts. This is a critical step for debugging and ensuring your tools function as expected.

_________________________________________________________________________________________

Prefer To Watch The Tutorial?

__________________________________________________________________________________________

1. Setting Up the MCP Server Connection

You must establish a new connection in Postman for the MCP server.

Step 1: Create a New Request

1. In Postman, click New or navigate to the New menu.
2. Select the MCP request type.

Step 2: Specify the MCP Server Path

1. In the Untitled Request tab that opens, make sure the Studio tab is selected in the request pane.
2. Enter the file path to your agent-payment-router executable in the command/URL field.
3. Note: If you installed the router using the npm install command from a previous lesson, the path might look similar to this (adjust for your operating system):

2. Configuring Environment Variables

Your MCP server requires authentication keys to link requests to your Agent Payment budget and account.

Step 3: Add Authentication Keys

1. Click the Settings tab within your new request.
2. Add the following required keys and their corresponding values, which you can retrieve from the Dashboard and Account Details pages of your Agent Payment account:

X_BUDGET_KEY (Required)

X_API_KEY (Required)

X_INSTANCE_METADATA (Optional)

1. Value Source: Custom JSON
2. Description: Used for logging, helps identify the request origin in your dashboard.

If using the optional X_INSTANCE_METADATA, the value should be a JSON string. An example for Postman is:

Step 4: Connect to the Server

1. Click the Connect button on the far right of the request URL bar.
2. A successful connection will show a green "Connected" status and load the available tools in the Message tab.

3. Testing an Integrated Tool

Once connected, you can use the Message tab to test any tools you have enabled on your Agent Payment budget.

Step 5: Execute a Tool Request

1. Switch to the Message tab.
2. Scroll down to the list of available tools (e.g., Complex-Mathematics-Engine).
3. Click on the tool you wish to test. This will populate the request with the required parameters.
4. Enter a test expression in the arguments field.

1. Note: The exact format and required parameters for the tool will be displayed in the interface.
2. Click the Run button.

4. Validating the Results

The response will appear in the Response pane at the bottom of the screen.

Step 6: Review the Local Response

1. Check the Response pane. The JSON output will contain the tool's result, execution time, and other metadata.
2. Look for the result field to confirm the expected output was generated by the tool.

Step 7: Verify the Transaction in the Dashboard

All requests made through the MCP server are logged in your Agent Payment account.

1. Log in to your Agent Payment Dashboard.
2. Navigate to the Agent Activity tab.
3. Select your budget from the dropdown menu.
4. Find the log entry corresponding to your Postman request. The Instance Metadata you set will help you identify it.
5. Click on the entry to view the full transaction details, including:
6. The exact Request Payload sent to the tool.
7. The complete Response Data from the tool.

This process ensures that your tools are correctly configured and provides clear visibility into all inputs and outputs before you start integrating them into your agent's language model prompts.