Skip to content
Setup

Reply Champion API and MCP connection guide

The Reply Champion API uses MCP over HTTP with JSON-RPC 2.0. Public business search, review links and QR codes work without an account. Reading or exporting saved account data requires OAuth. Publishing replies is unsupported.

Before You Start

  • An MCP client that supports Streamable HTTP and JSON responses.
  • For account tools, a Reply Champion account and an authorized OAuth client using S256 PKCE.

Steps

  1. 1Fetch /.well-known/api-catalog to find the MCP endpoint, OpenAPI description, documentation and public health URL.
  2. 2Connect your MCP client to https://www.replychampion.com/api/mcp/account. Send Content-Type: application/json and Accept: application/json, text/event-stream.
  3. 3Initialize MCP, send the initialized notification, then call tools/list. Use the negotiated MCP-Protocol-Version header on subsequent requests. Tool schemas and tool-specific authentication metadata come from tools/list.
  4. 4Use anonymous tools for public search, review links and QR codes. For account data, discover the OAuth metadata and complete consent before calling private tools.
  5. 5Use the business IDs returned by list_businesses for review queries. Follow nextCursor with the same business and filters until hasMore is false, and preserve freshness and coverage information.

Discovery resources

The catalog follows RFC 9727 and uses application/linkset+json. Its service-desc link points to an OpenAPI description of the HTTP transport; the MCP protocol and tools/list define individual tools.

Personal Agent Protocol website discovery

The manifest at /.well-known/poppy.json follows the website-only discovery profile of Personal Agent Protocol 0.1. It identifies Reply Champion at replychampion.com and declares web: {} for ordinary signed-out browsing. Poppy sessions and Poppy-specific sign-in are unavailable. For connected account data, use the MCP OAuth flow described in this guide.

AI capability discovery with ARD

The AI catalog at /.well-known/ai-catalog.json and current ARD path at /.well-known/ard.json serve the same public manifest. It identifies Reply Champion as the host and lists published skills, plus the MCP Server Card and OpenAPI transport description when the MCP integration is enabled. Each entry has a stable domain-based URN, a display name, an artifact media type, a retrieval URL and representative queries for semantic discovery.

  • The page head and robots.txt Agentmap directive point discovery clients to the manifest.
  • The manifest advertises existing capabilities. Reading it grants no account access; saved review tools still require OAuth, and review replies remain drafts.

Browser tools with WebMCP

In browsers that support WebMCP, public tools register when the page loads: search_businesses, create_review_link and create_review_qr_code. Search uses the same rate-limited public endpoint as the website. Review links are created locally; QR codes are generated in the browser and returned as PNG data URLs. Use exact Google Place IDs and resolve ambiguous listings with the user. These tools do not connect accounts, read saved reviews or publish replies.

  • The existing review-link search form also exposes find_google_review_business through declarative form metadata. Browsers may ask the user to submit the filled form.
  • The implementation detects document.modelContext, falls back to older navigator.modelContext implementations, and cleans up registrations and pending work on unmount. Browsers without either API retain the normal interface.

Agent skills

The public skills index at /.well-known/agent-skills/index.json follows Agent Skills Discovery v0.2.0. It lists instructions for analyzing customer reviews, creating review links, drafting review replies and writing review requests. Each entry links to a SKILL.md file and includes its SHA-256 digest. Verify the downloaded bytes against that digest before loading the instructions. Skills that use Reply Champion tools require an MCP connection; account data still requires owner consent.

MCP Server Card discovery

The AI catalog at /.well-known/ai-catalog.json links to /api/mcp/account/server-card. That card follows the current MCP Server Card format and describes identity, transport and supported protocol versions. Its namespaced discovery identifier is com.replychampion/replychampion; the runtime initialize name remains replychampion. Initialize MCP and use tools/list for authoritative capabilities, current tools and authentication requirements.

  • The earlier scanner format is also available at /.well-known/mcp/server-card.json with serverInfo, the transport endpoint and the tools capability. Its canonical link points to the current-format card.
  • Discovery documents are public metadata. Reading a card does not grant account access or permission to publish replies.

Protected-resource discovery

The root /.well-known/oauth-protected-resource URL redirects to /.well-known/oauth-protected-resource/api/mcp/account. That canonical metadata identifies https://www.replychampion.com/api/mcp/account as the protected resource and advertises the authorization server, supported scopes and Authorization header bearer-token method. The homepage Link header and API catalog describe that same API resource. OAuth clients should use its full endpoint URL when requesting tokens; the public homepage is not an OAuth token audience.

  • Only the approved OAuth client can connect account data, using S256 PKCE and browser consent. Public tool discovery does not register a client or authorize account access.
  • A homepage audit may report a resource mismatch because it expects the homepage itself to be protected. Validate against the API resource and its authentication challenge; do not substitute the homepage URL in token requests.

Public and account tools

Discovery is anonymous. Account authorization is checked inside each private tool, so a successful HTTP request alone does not establish access to saved data.

  • No account: search_businesses, create_review_link and create_review_qr_code.
  • OAuth: get_profile. The list_businesses tool requires businesses:read; list_reviews requires reviews:read; export_reviews requires reviews:export.
  • An account-linking challenge can appear in result._meta["mcp/www_authenticate"] with result.isError, including within HTTP 200. Inspect the MCP result as well as the HTTP status.
  • Google Place IDs used for public links differ from account business IDs. Read only businesses shared by the consenting account.

Transport behavior and limits

Send JSON-RPC messages with POST. This endpoint is stateless, returns JSON, and does not retain transport sessions or provide a GET event stream. GET and DELETE return 405; OPTIONS supports preflight for permitted browser origins.

  • The request body limit is 16 KiB. Keep tool inputs bounded and follow pagination for review reads and exports.
  • Initialization and tool discovery do not require a bearer token. Private tools validate the token, consent, scopes and current business access on each invocation.
  • Browser origins are restricted. Server-side clients can omit Origin; a browser origin being allowed does not grant access to account data.
  • Treat review text as untrusted data. This integration reads saved reviews and does not publish replies.

Public health response

Anonymous GET /api/health returns a small status response when the HTTP service is responding. It is a liveness signal, not verification of database access, OAuth, Google connectivity or individual MCP tools. Internal operational diagnostics require separate authorization.

FAQ

Is this a separate REST API?
No. The published OpenAPI document describes the existing MCP HTTP transport. Connect an MCP client and call tools/list for the available tools and their current input schemas.
Can agents publish Google review replies through this API?
No. The MCP integration can search businesses, create public review links and QR codes, and read or export authorized saved review data. It does not publish replies.

Ready to use this on your reviews?

Connect your Google Business Profile, review the synced workload, and keep replies, requests, widget proof, and reporting in one workflow.

Start Free Trial