Consumer Documentation

Overview

As a consumer, you can discover tools on the marketplace and invoke them via API. AgentPatch handles authentication, billing, and request routing.

CLI (Recommended)

The CLI is the simplest way to get started. For MCP integration, see below.

Install the AgentPatch CLI (zero dependencies, Python 3.10+):

pip install agentpatch

Set your API key:

export AGENTPATCH_API_KEY=your_api_key

Then use it:

ap search "web search"
ap run agentpatch google-search --input '{"query": "test"}'

Get your API key from the AgentPatch dashboard.

CLI Commands

MCP Interface

AgentPatch provides an MCP (Model Context Protocol) server for AI assistants.

Claude Code

Run this command to add AgentPatch as an MCP server:

claude mcp add -s user --transport http agentpatch https://agentpatch.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with your actual key from the AgentPatch dashboard. Claude Code discovers all AgentPatch tools automatically.

OpenClaw

Add AgentPatch to ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "agentpatch": {
        "transport": "streamable-http",
        "url": "https://agentpatch.ai/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

Replace YOUR_API_KEY with your actual key from the AgentPatch dashboard. Restart OpenClaw and it discovers all AgentPatch tools automatically.

Cursor

1. Open Cursor Settings (Cmd+Shift+J on Mac, Ctrl+Shift+J on Windows/Linux).
2. Navigate to the MCP section in the sidebar.
3. Click Add new global MCP server.
4. Cursor opens ~/.cursor/mcp.json. Add the AgentPatch server config:

{
  "mcpServers": {
    "agentpatch": {
      "url": "https://agentpatch.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

5. Replace YOUR_API_KEY with your actual key from the AgentPatch dashboard.
6. Save and restart Cursor. It discovers all AgentPatch tools automatically.

Codex

Add AgentPatch to ~/.codex/config.toml:

[mcp_servers.agentpatch]
url = "https://agentpatch.ai/mcp"
bearer_token_env_var = "AGENTPATCH_API_KEY"

Then set your API key:

export AGENTPATCH_API_KEY=your_api_key

Replace your_api_key with your actual key from the AgentPatch dashboard. Codex discovers all AgentPatch tools automatically on next start.

Generic MCP Client

Connect to one of these endpoints:

• Streamable HTTP: https://agentpatch.ai/mcp
• SSE: https://agentpatch.ai/mcp/sse

Available MCP Tools

• search_tools — Find tools by query
• get_tool_details — Get tool info and schemas
• invoke_tool — Call a tool and get results
• get_job_status — Check job status

Pass your API key via the api_key argument when invoking tools.

API Reference

The full API specification is available as an OpenAPI spec (JSON), or you can explore it interactively via the Swagger UI.

Authentication

All API requests require an API key in the Authorization header:

Authorization: Bearer your_api_key_here

Get your API key from the Dashboard after logging in.

Finding Tools

Browse the Marketplace

Visit the Browse page to see available tools with their descriptions, pricing, and success rates.

List All Tools

GET /api/tools

Returns every active tool with names, descriptions, pricing, input/output schemas, and invocation examples. No authentication required.

Search API

GET /api/search?q=screenshot&max_price_credits=5000&limit=20

Omitting the q parameter returns all tools (equivalent to the list endpoint above, with additional filtering options).

Query parameters:

Get Tool Details

GET /api/tools/{username}/{slug}

Returns tool metadata including input/output schemas and pricing. The {username} is the tool provider’s username, available as owner_username in list and search results.

Invoking Tools

POST /api/tools/{username}/{slug}?timeout_seconds=120
Authorization: Bearer your_api_key
Content-Type: application/json

{
  "url": "https://example.com",
  "format": "png"
}

The {username} is the tool provider’s owner_username from the list or search results. The request body is the tool input directly, matching the tool’s input_schema. The timeout_seconds query parameter is optional (max 3600).

Synchronous Response (200)

When the tool completes within the timeout:

{
  "job_id": "job_abc123",
  "status": "success",
  "output": { ... },
  "latency_ms": 2100,
  "credits_used": 10,
  "credits_remaining": 9990
}

Async Response (202)

For long-running tasks, you receive a job ID to poll:

{
  "job_id": "job_abc123",
  "status": "pending",
  "poll_url": "/api/jobs/job_abc123",
  "credits_reserved": 10,
  "credits_remaining": 9990
}

Error Response

{
  "job_id": "job_abc123",
  "status": "failed",
  "error": "Tool returned status 400: Invalid URL format",
  "credits_used": 0,
  "credits_remaining": 10000
}

All invocation responses include credits_remaining so your agent can track its budget without extra API calls.

Polling for Results

For async jobs, poll the job endpoint until status changes:

GET /api/jobs/{job_id}
Authorization: Bearer your_api_key

Response:

{
  "job_id": "job_abc123",
  "tool_id": "tl_xyz",
  "status": "success",
  "output": { ... },
  "latency_ms": 45000,
  "credits_used": 10,
  "created_at": "2026-01-28T10:00:00Z",
  "completed_at": "2026-01-28T10:00:45Z"
}

Status Values

Polling Guidelines

• Poll every 10 seconds for quick jobs
• Poll every 30-60 seconds for longer jobs
• Output is available for 24 hours after completion
• Maximum output size is 1 MB

Credits

Credit System

• 1 credit = $0.0001 USD (10,000 credits = $1.00)
• Credits are deducted when you invoke a tool
• Failed invocations (5xx, timeout) are refunded
• Check your balance at GET /api/my/balance

Top-ups

Add credits via Stripe Checkout:

POST /api/my/topup
{
  "amount_credits": 250000
}

This returns a Stripe Checkout URL. Complete payment and credits are added automatically.

Available amounts: $25, $50, $100.

Refund Policy

The 4xx penalty resets after a successful call or 24 hours.