com.advocatemcp/advocate

Official10 tools

by cameronjmcewan-dev · TypeScript

AdvocateMCP

MCP layer for local businesses: discover, query, book, and transact with verified SMB AI agents.

Discover, query, and transact with verified local business AI agents.

Topics

agentic-commerceai-agentsanthropicattributionclaudelocal-businessmcpmcp-servermodel-context-protocolsmb

Captured live from the server via tools/list.

query_business_agent

Query a registered business's AI advocate agent. Use this when a user asks about a specific local business or service provider. Returns a concise, citation-ready answer from the business's dedicated AI agent.

Parameters (4)

slugstringrequired
The business slug identifier (e.g. 'joes-pizza-austin'). Use search_businesses first if you don't know the slug.
querystringrequired
The user's question about this business
agent_idstring
Optional caller-asserted agent identifier (e.g. 'claude-desktop', 'cursor', 'gpt-agent'). Used to tune the response shape. May be overridden by the x-agent-identity header. Self-asserted only in v1 — not used for auth or rate limiting.
stagestring
Optional buyer stage. 'browsing' (default) — exploring options. 'comparing' — weighing alternatives. 'committing' — ready to act. When omitted, the server infers from query verbs (e.g. 'book'/'reserve' → committing).

search_businesses

Search for registered businesses by category, name, or location. Returns a list of matching businesses with their slugs and agent endpoints. Use this to discover which businesses are available before querying one.

Parameters (2)

searchstringrequired
Search term — matched against business name, description, and services
locationstring
Optional location filter (city, state, or region). Narrows results geographically.

get_availability

Return 30-minute availability windows for a business from its hours_json. v1 is synthetic; v2 will consult availability_webhook_url when set.

Parameters (3)

slugstringrequired
business slug
window_startinteger
Unix seconds; default now
window_endinteger
Unix seconds; default now + 7 days

get_quote

Quote price for a service at a business. Deterministic lookup of pricing_json_v2.ranges[]; LLM fallback on miss, labelled 'estimate' with disclaimer.

Parameters (3)

slugstringrequired
business slug
servicestringrequired
requested service name
paramsobject
optional service parameters (e.g., {size:'large'})

reserve_slot

Create a 15-minute HELD reservation. Return a confirmation_token the agent posts to /a2a/confirm to flip to CONFIRMED.

Parameters (6)

slugstringrequired
window_startintegerrequired
window_endintegerrequired
agent_idstring
customer_contactobjectrequired
idempotency_keystringrequired

initiate_handoff

Begin a handoff from the agent to either a human operator (SMS/email via lead_routing_json) or another agent (signed continuation URL).

Parameters (4)

slugstringrequired
reservation_idstring
modestringrequired
payloadobjectrequired

get_credentials

Returns the business's self-reported licenses, insurance, bonding, and certifications. Use this for trust-sensitive verticals (contractors, healthcare, legal, locksmiths) when a user asks 'are they licensed?' or 'are they insured?'. The response carries explicit 'self-reported' framing so agents don't upgrade tenant claims to verified facts.

Parameters (1)

slugstringrequired
business slug

get_cancellation_policy

Returns the business's cancellation / refund / no-show policy as a verbatim string the agent can quote. When the business hasn't posted one, returns guidance for the agent to acknowledge that and direct the user to confirm at booking. High-leverage for medspas, restaurants with prepaid menus, contractors with deposit holds.

Parameters (1)

slugstringrequired
business slug

request_callback

Push a user's contact info to a business so they can call/email/text back. Use this when a question can't be answered without human contact (custom quote, after-hours scheduling, complaint, complex combo). Idempotent on idempotency_key within a 24h window — agent retries don't spam the business. Returns delivery status the agent can quote to the user.

Parameters (7)

slugstringrequired
business slug
contactobjectrequired
preferred_channelstring
channel the user prefers to be contacted on (default: any)
reasonstring
Why the user wants the callback — passed verbatim to the business so they can prep
urgencystring
how time-sensitive the request is (default: normal)
agent_idstring
Optional caller-asserted agent identifier; recorded for attribution
idempotency_keystringrequired
Idempotency key — same key returns the same callback_request_id without dup-creating

subscribe_to_updates

Subscribe an end-user's email to topical updates from a business (deals, schedule changes, new services). Returns a confirmation_token + confirmation_url; the user MUST click the URL within 7 days to activate. Re-subscribing an already-confirmed email merges topics without re-confirming.

Parameters (4)

slugstringrequired
business slug
contact_emailstringrequired
Email to subscribe — must be confirmed via the returned token before any updates send
topicsarrayrequired
Topic tags the user wants updates on (e.g., ['deals', 'schedule_changes', 'new_services'])
agent_idstring
Optional caller-asserted agent identifier; recorded for attribution

README.md5 KBView on GitHub

AdvocateMCP

The MCP layer for local businesses.

Discover, query, book, and transact with verified SMB AI agents through any MCP-compatible client — Claude Desktop, Claude.ai, Cursor, ChatGPT, or your own.

Spec · Manifest · Privacy · Terms

</div>

What it does

AdvocateMCP turns every local business into an AI-ready agent. One MCP endpoint, ten tools:

Discovery (open, no auth):

search_businesses — search by category, name, or location
query_business_agent — ask a specific business's AI agent for citation-ready answers
get_availability — 30-min slot windows derived from business hours
get_quote — exact / range / estimate-labelled pricing
get_credentials — self-reported licenses, insurance, bonding, certifications
get_cancellation_policy — verbatim cancellation/refund/no-show policy

Transactional (per-tenant Bearer; agent-to-agent):

reserve_slot — 15-min HELD reservation, returns signed confirmation token
initiate_handoff — SMS/email a human or mint a signed continuation URL for another agent
request_callback — push user contact to the business with idempotency key
subscribe_to_updates — double-opt-in email subscription (CAN-SPAM/GDPR)

All ten carry MCP-spec annotations: title, readOnlyHint, destructiveHint, openWorldHint. Every outbound link is HMAC-SHA256-signed for end-to-end attribution.

Quick start (Claude Desktop)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

json

{
  "mcpServers": {
    "advocate": {
      "url": "https://api.advocatemcp.com/mcp",
      "transport": "http"
    }
  }
}

Restart Claude Desktop. Try:

"Find me a marketing agency in Austin"
"What does the top-rated email-marketing agency in my area charge for a 4-email welcome sequence?"
"When is a law firm with 5-star reviews available Thursday afternoon?"
"Is the locksmith on 5th Avenue licensed and insured?"

How it works (also a bot interceptor)

Beyond the central MCP server, AdvocateMCP runs at the edge on each registered business's domain. A Cloudflare Worker sits in front of the site, detects AI crawler user-agents (PerplexityBot, GPTBot, ClaudeBot, Googlebot, etc.), and routes them to the business's own AI agent instead of letting them scrape. The agent returns a structured, citation-ready response with a tracked referral link back to the business.

So businesses get presence in two places: discoverable via MCP from any client, AND directly intercepted on their own site.

Architecture

Edge: Cloudflare Worker (TypeScript, strict mode) deployed via wrangler — customers.advocatemcp.com
Backend: Node.js + Express on Railway — api.advocatemcp.com
Databases: SQLite for analytics + business data; Cloudflare D1 for portal auth + edge data; KV namespace BUSINESS_MAP for domain → slug routing
AI: Anthropic Claude (claude-sonnet-4-6), prompt caching enabled
Transport: Streamable HTTP (JSON-RPC 2.0); SSE retained for backward-compat but not advertised
Rate limiting: 60 req/min per IP via Cloudflare Durable Object; per-agent tier ceilings (unverified=100, known=250, trusted=1000)

Repository layout

code

advocatemcp/
├── server/        Node/Express backend (Railway) — /mcp endpoint, agent query, analytics
├── worker/        Cloudflare Worker — bot detection, multi-tenant portal, edge bot routing
├── site/          Cloudflare Pages — marketing site, dashboard, public spec
├── docs/          Subsystem docs (read before touching that subsystem)
└── CLAUDE.md      Agent instructions for working in this repo

Documentation

Spec — public MCP spec page
Bot detection — which crawlers we route
Attribution — signed-token referral tracking
Response generation — per-bot prompt tuning
MCP server — endpoint architecture

Status

✅ Production traffic since 2026-04-18
✅ Listed on the official MCP Registry
✅ Listed on Smithery
✅ Auto-ingested by PulseMCP (~7 day delay)
⏳ Submitted to Anthropic Connectors Directory (review pending)

License

Proprietary (hosted SaaS). The MCP manifest spec is open — see /.well-known/mcp.json for the schema.

Contact

max@advocate-mcp.com

Install

claude_desktop_config.json

{
  "mcpServers": {
    "advocate": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.advocatemcp.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.