ads4agents-mcp

MCP server for ads4agents — hire marketing agencies and run ad campaigns from any AI agent.

Prerequisite: Conway Terminal

Campaign creation on ads4agents costs 0.50 USDC via x402 (USDC on Base). Payment is handled by Conway Terminal, which must be installed and running alongside this server.

npx conway-terminal

Conway Terminal provisions an EVM wallet at ~/.conway/wallet.json and exposes an x402_fetch tool that auto-handles 402 payment challenges. ads4agents-mcp delegates all payment logic to it.

Tools

| Tool | Description | |------|-------------| | ads4agents_register_agent | Register a new agent profile and get an API key | | ads4agents_list_agencies | Search agencies by region, specialty, and budget | | ads4agents_get_agency | Get full agency profile and reviews | | ads4agents_list_services | Browse active services offered by agencies | | ads4agents_get_service | Get full service detail including agency info | | ads4agents_open_inquiry | Start a free pre-purchase chat with an agency | | ads4agents_get_inquiry_messages | Read messages in an inquiry thread | | ads4agents_send_inquiry_message | Reply in an inquiry thread | | ads4agents_get_campaign | Get campaign status and details | | ads4agents_get_campaign_messages | Read messages in a campaign thread | | ads4agents_send_campaign_message | Send a message to the agency on a campaign | | ads4agents_update_campaign_payment | Record payment tx hash after Conway x402_fetch |

Campaign creation is done via Conway Terminal's x402_fetch tool directly — see Campaign creation below.

Quickstart

1. Install Conway Terminal

npx conway-terminal

Follow the setup wizard — it creates your wallet and adds itself to Claude Code / Claude Desktop automatically.

2. Add ads4agents-mcp

claude mcp add ads4agents -- npx ads4agents-mcp

Or add to your MCP config manually (see Configuration).

3. Register your agent

Call ads4agents_register_agent once. Pass your Conway wallet address so it matches the wallet that pays for campaigns.

{
  "business_name": "My SaaS",
  "business_description": "Project management for remote teams",
  "wallet_address": "0xYourConwayWalletAddress"
}

Store the returned api_key as ADS4AGENTS_API_KEY.

4. Find a service

{ "specialty": "SEO", "max_price": 500 }

5. Open an inquiry (optional)

Ask the agency questions before committing:

{
  "agency_id": "<uuid>",
  "service_id": "<uuid>",
  "initial_message": "Do you work with B2B SaaS companies?"
}

6. Campaign creation

Use Conway Terminal's x402_fetch tool — it handles the 402 payment challenge automatically:

x402_fetch("https://ads4agents.net/api/campaigns", {
  method: "POST",
  headers: {
    "X-Agent-Key": "<ADS4AGENTS_API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agency_id: "<uuid>",
    service_id: "<uuid>",
    title: "Q3 SEO push",
    budget: 1000,
    duration_days: 30,
    regions: ["US"],
    target_audience: "B2B SaaS decision makers"
  })
})

Then record the tx hash:

ads4agents_update_campaign_payment({
  id: "<campaign_id>",
  payment_tx_hash: "<txHash from x402_fetch response>"
})

Configuration

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | ADS4AGENTS_API_KEY | After registration | Your agent API key from ads4agents_register_agent | | ADS4AGENTS_BASE_URL | No | Override API base URL (default: https://ads4agents.net) |

No PRIVATE_KEY needed — payment signing is handled by Conway Terminal.

Claude Code setup

{
  "mcpServers": {
    "ads4agents": {
      "command": "npx",
      "args": ["ads4agents-mcp"],
      "env": {
        "ADS4AGENTS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop setup

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ads4agents": {
      "command": "npx",
      "args": ["ads4agents-mcp"],
      "env": {
        "ADS4AGENTS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Requirements

• Node.js >= 20
• Conway Terminal installed and configured

License

MIT