Apps Documentation

MCP Tools

Connect MCP servers so agents can act on your systems — with mandatory human approval on every call.

Overview

MCP Tools lets you connect any Model Context Protocol server (CRM, warehouse, internal API) to Adverfly. Once connected, the tools the server exposes become available to Adverfly's AI agents alongside the built-in ones.

The hard rule: every MCP tool call queues for human approval. Nothing runs on your systems until a person clicks Approve. There are no exceptions — read tools, write tools, and side-effect-free queries all queue the same way.

How it works

  1. Connect a server in the MCP app. Adverfly probes it (initialize + tools/list) and shows the discovered tools.
  2. Agent decides to use a tool during a chat or scheduled run. Instead of calling your server, Adverfly inserts a row in the approval queue and tells the agent "queued — wait for the user."
  3. You approve or reject in the MCP app. On approve, Adverfly calls your server, captures the response, and marks the action executed.
  4. History shows every call with status, timestamps, and approver.

Try it with the built-in simulator

Adverfly ships a fake-Meta MCP server you can connect to before wiring up anything real. It has 5 simulated tools (list_campaigns, pause_campaign, set_daily_budget, etc.) backed by in-memory state.

Endpoint: https://www.adverfly.com/api/mcp-simulator/meta

Connect:

  1. Open the MCP app → Add MCP Server
  2. Name: Meta Simulator
  3. Endpoint URL: https://www.adverfly.com/api/mcp-simulator/meta
  4. Auth token: leave empty
  5. Connect — you should see 5 tools discovered

Trigger an action:

  • Open Cortex chat and ask: "Pause campaign camp_001 on Meta"
  • The agent queues the call — check the MCP app's "Pending approval" section
  • Approve it — Adverfly hits the simulator

Verify:

  • Open the same URL in your browser (GET) → JSON dump of campaign state + recent logs
  • You'll see camp_001.status is now PAUSED and a log entry for the call

The simulator state is in-memory and resets on cold start. Use it for smoke tests, not for anything stateful you care about.

Advanced: test the simulator without connecting it

If you want to confirm the simulator endpoint works before going through the Adverfly UI:

Direct curl — list tools without any Adverfly involvement:

curl -X POST https://www.adverfly.com/api/mcp-simulator/meta \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Then call a tool directly:

curl -X POST https://www.adverfly.com/api/mcp-simulator/meta \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"pause_campaign","arguments":{"campaign_id":"camp_001"}}}'

Re-open the URL in the browser to see the updated campaigns state and a new log entry.

Testing against a local Adverfly dev server with ngrok — if you're building a custom MCP server on your laptop and want Adverfly to reach it:

ngrok http 3000     # exposes your local server publicly

Use the printed https://<id>.ngrok.io/<path> URL when adding the MCP server in Adverfly. The Adverfly backend Lambda will hit your laptop through the tunnel.

Connecting your own server

Your MCP server needs to speak JSON-RPC 2.0 over HTTP and implement at minimum:

  • initialize — returns protocolVersion and serverInfo
  • tools/list — returns the tool catalog
  • tools/call — executes a tool by name with arguments

Authentication is a Bearer token, set when you connect the server. Adverfly encrypts the token at rest.

If your existing MCP is stdio-only (the official reference servers are), put a bridge in front of it (mcp-proxy, supergateway) that exposes HTTP.

Getting started

  1. Open MCP Tools from the sidebar (under Activate)
  2. Connect the Meta simulator first to confirm the flow works
  3. Connect your real server
  4. Trigger an agent action and approve from the queue