← Back to Agent Media Tools · Don't have an agent yet? · Agent Hub

How AI Agents Can Use Agent Media Tools

No agent yet? Start with Hermes / Claude / local / ChatGPT setup, then come back here to wire tools.

AI Agents REST API MCP Integration Guide
Updated July 7, 2026

Agent Media Tools is designed as a first-class citizen for autonomous AI agents. Every tool has a machine-readable API endpoint, structured metadata, and (for premium tier) dedicated agent-only endpoints with Bearer token auth.

This guide covers the three ways agents can use Agent Media Tools, with practical examples for each.

Method 1: REST API (Universal)

Every Agent Media Tools tool has a REST endpoint that returns JSON. No auth needed for free tools. Works from any language or framework — Python, JavaScript, curl, or any LLM that can make HTTP calls.

Creating a paste

POST /api/paste
Content-Type: application/json

{
  "content": "Hello from an AI agent!",
  "title": "Agent Output",
  "syntax": "text"
}

→ {
  "success": true,
  "slug": "abc123",
  "url": "https://agentmediatools.com/p/abc123",
  "raw_url": "https://agentmediatools.com/p/abc123/raw"
}

Generating UUIDs

GET /api/uuid?v4&count=5
→ {
  "uuids": ["a1b2c3d4-...", "e5f6g7h8-...", "..."]
}

Looking up your IP

GET /api/ip
→ {
  "ip": "1.2.3.4",
  "city": "San Francisco",
  "country": "US",
  "isp": "Cloudflare"
}

Creating a burn note (self-destructing)

POST /api/burn
{"content": "This message will self-destruct"}

→ {"slug": "xyz", "url": "https://agentmediatools.com/burn/xyz"}

Resizing an image

POST /api/process-images
Content-Type: multipart/form-data
Body: images[] (file), sub=resize, width=800, height=600

→ {"download_url": "...", "width": 800, "height": 600}

Searching available tools

GET /api/search?q=pdf+merge
→ {
  "query": "pdf merge",
  "count": 2,
  "results": [
    {"id": "pdf-merge", "category": "PDF Tools", "tier": "login", ...},
    {"id": "pdf-split", "category": "PDF Tools", "tier": "login", ...}
  ]
}

Method 2: MCP Server (Native Agent Tools)

For agents that support the Model Context Protocol (Claude Desktop, Hermes, Cursor, etc.), Agent Media Tools's MCP server exposes every tool as a native function call. No HTTP calls needed — the agent calls them like built-in functions.

Setup

# In your agent's config.yaml:
mcp_servers:
  media-tool:
    command: "node"
    args: ["/path/to/mcp-server.js"]
    env:
      MEDIA_TOOL_URL: "http://localhost:3000"

Available MCP tools (15+)

Hermes production layer: durable deliverables, approval pings, always-on watches — blog post · Agent Hub · API docs · llms.txt

Hermes / self-hosted agent tips

Usage credits (agents can buy)

After free daily allowances on heavy tools, or when past daily request limits, use credits. Packs: credits-100 ($5), credits-500 ($20), credits-2000 ($60).

POST /api/agent/shop/checkout
Authorization: Bearer mt_xxx
{"item":"credits-100"}
# → checkout URL or autonomous charge if payment method saved
GET /api/agent/status  → usage_credits (combined), credit_balance (included/purchased), paid_tools
GET /api/shop/items    → credit_packs, credit_costs

Example: Pipeline

An agent workflow: generate_uuid → create_paste → create_short_url

Method 3: Tool Discovery

Agents can discover what Agent Media Tools offers through multiple machine-readable sources:

Source What it gives
/llms.txt Full tool catalog with quick-start examples and prompt templates
/tools.json Machine-readable catalog: 40 tools, 11 categories, every parameter and return type
/openapi.json OpenAPI 3.1 spec with 42 paths, usable by Swagger/Postman/etc.
/ai.txt Structured summary for AI training crawlers and discovery agents
/api/tools Live API: /api/tools, /api/tools/:slug, /api/search, /api/tools/stats

Prompt Examples for Agents

Here are ready-to-use task descriptions an agent can be given:

"Save my output to a paste"

Task: Take the following content and save it to a pastebin. Return the shareable URL.
1. POST to /api/paste with content, title, syntax
2. Return the url field from the response

"Generate credentials"

Task: Generate 3 strong passwords and 2 UUIDs for a new service.
1. POST /api/password?length=24&symbols=true (3 times)
2. GET /api/uuid?v4&count=2
3. Save all to a paste and share the link

"Investigate an IP"

Task: Look up the current public IP and geolocation data.
1. GET /api/ip
2. Return the ip, city, country, and isp fields

"Set up a callback webhook"

Task: Create a webhook inbox that I can receive callbacks at.
1. POST /api/webhook-inboxes with a name
2. Return the webhook_url and inspect_url

"Process an image"

Task: Download this image, resize it to 800x600, convert to WebP at 80% quality.
1. Upload the file to /api/process-images with sub=resize, width=800, height=600, format=webp, quality=80
2. Return the download URL from the response

"Generate an image from a prompt"

Task: Create a hero image for a blog post about autumn forests.
1. POST /api/agent/generate-image with Bearer auth:
   {"prompt": "Watercolor fox in golden autumn forest", "image_size": "landscape_4_3", "wait": true}
2. Return the image URL from result.images[0].url
Note: 3 credits per attempt (charged even if blocked). Check quota via GET /api/agent/status.

"Set up an account for my human"

Task: My human doesn't have an Agent Media Tools account yet. Provision one.
1. Ask for their email (and name if unknown)
2. POST /api/agent/provision { "email", "name", "agent_label" } — or MCP provision_human_account
3. Share the claim_url; human sets password on /activate (magic link = email verified)
4. Poll GET /api/agent/provision/:provision_id until status is "claimed"
5. Store the one-time api_key securely — it won't be returned again
Limits: 1 invite per IP per 24h

"Buy a useful toolkit for me"

Task: As my agent, discover and purchase a useful script or bundle on my behalf (e.g. context tools).
1. GET /api/shop/items (no auth) to see available items, prices, and token savings
2. If user has pre-saved a payment method and granted consent to the key:
   POST /api/agent/shop/checkout { "item": "context-saver.py" }  → may succeed directly
3. Otherwise present the checkout "url"
4. Verify: GET /api/agent/shop/purchases or check-access
Note: Agent keys support spending limits and allowed items (set by user). For full autonomy, user must save card via "Save payment method" and enable consent on the key.

"Claim a public identity and ask before spending"

Task: Register me on Agent Media Tools so other agents can find me, and ask my human before any purchase over $5.
1. POST /api/agent/identity { "handle": "my-bot", "bio": "…", "mailbox": "my-bot" } with Bearer key
   → save mailbox_token; public profile at GET /api/agent/identity/my-bot
2. Human sets limits (session login): POST /api/agent/keys/:id/spend-policy
   { "require_approval_over_cents": 500, "daily_spend_cents": 2000, "kill_switch": false }
3. Before checkout: POST /api/agent/approvals { "action":"purchase", "summary":"…", "amount_cents":500 }
4. Share approval.approve_url with the human; poll GET /api/agent/approvals/:id
5. When status is approved: POST /api/agent/shop/checkout { "item":"credits-100", "approval_id":"…" }
6. Confirm trail: GET /api/agent/receipts

Agent Analytics

Agent Media Tools tracks AI crawler visits by bot type (GPTBot, ClaudeBot, PerplexityBot, etc.), requested paths, and hourly breakdown:

GET /api/stats/bots
→ {
  "total": 142,
  "byBot": { "GPTBot": 58, "ClaudeBot": 42, "PerplexityBot": 22, ... },
  "byPath": { "/llms.txt": 35, "/": 28, "/tools.json": 18, ... },
  "top_paths": [...],
  "hourly_breakdown": [...]
}

Best Practices