Agent platform

RCS Surveys is agent-native

Beyond a human dashboard. One authenticated gateway lets an autonomous AI agent discover, author, clone, render, send, and read the results of RCS surveys programmatically — reused by an MCP server, a CLI, and an embeddable client, all over a single typed contract so they can never drift.

Quickstart Tool catalog GitHub

Gateway

/api/agent/*

Surfaces

MCP · CLI · client

Tools

one per call

Skill chains

least-privilege

Architecture

One gateway, three skins

The agent toolkit is a thin client over the /api/agent gateway, which reuses the exact same services the human app calls — marketplace, render, send, results, Studio. No business logic is forked. Pick the skin that fits your agent.

MCP server

Pro

rcs-surveys-mcp

A hand-rolled Model Context Protocol server (newline-delimited JSON-RPC over stdio, zero runtime deps). Register it once and Claude — or any MCP host — can search, render, clone, author, send, and read the results of surveys as native tools.

claude mcp add rcs-surveys \
  --env RCS_GATEWAY_URL=https://your-server \
  --env RCS_AGENT_KEY=rcsk_live_… \
  -- npx -y @rcs-surveys/agent-toolkit rcs-surveys-mcp

CLI

Pro

rcs-survey

A thin, scriptable mirror of the gateway. Every command prints JSON, so it composes with jq, drops into CI, or runs as a step inside a shell-driven agent loop.

rcs-survey search "customer satisfaction" --channel RCS --sort rating
rcs-survey render <id> --var firstName=Ada
rcs-survey clone <id>
rcs-survey send <blueprintId> --to +15551112222 --var firstName=Ada
rcs-survey results <surveyId>

Typed client

GatewayClient

Import GatewayClient + the shared TOOLS catalog from @rcs-surveys/agent-toolkit and call the gateway directly from your service. The same typed client powers the MCP server and the CLI.

import { GatewayClient, TOOLS } from '@rcs-surveys/agent-toolkit';

const client = GatewayClient.fromEnv();
const { items } = await client.call({
  method: 'GET',
  path: '/surveys',
  query: { q: 'nps' },
});

ProThe packaged MCP server and CLI ship on the Pro plan. The underlying gateway and typed client are available to embed in your own service.

Quickstart

From key to first call in three steps

Everything below works in local or preview without payment configured — a scoped key transacts against your org's existing metered billing.

Mint a scoped key

Pro

On a Pro plan, an org admin mints an agent key with exactly the scopes a job needs. The plaintext is shown once.

POST /api/agent-keys
{ "name": "my-bot",
  "scopes": ["surveys:read",
             "marketplace:clone"] }

→ { data: { key: "rcsk_live_…" } }

Point the toolkit at your server

Two environment variables configure every surface — MCP, CLI, and the embedded client.

export RCS_GATEWAY_URL=https://your-server
export RCS_AGENT_KEY=rcsk_live_…

Call it

claude mcp add rcs-surveys \
  --env RCS_GATEWAY_URL=https://… \
  --env RCS_AGENT_KEY=rcsk_live_… \
  -- npx -y @rcs-surveys/agent-toolkit \
     rcs-surveys-mcp

Tool catalog

Ten tools, one call each

Every tool maps to exactly one gateway endpoint and is gated by a scope — so a key only ever does what it was minted to do. These are the names the MCP server exposes; the CLI mirrors them verb-for-verb.

capabilities

$ rcs-survey capabilitiesany key

Machine-readable map of the gateway: every endpoint, the scopes your key actually holds, and the pricing seam (null today).

search_surveys

$ rcs-survey searchsurveys:read

Discover survey templates by query, channel (RCS/WhatsApp/SMS), and type — Net Promoter Score, Customer Satisfaction, Customer Effort, and more. Sort by rating or by most-cloned.

get_survey

$ rcs-survey getsurveys:read

Fetch one survey — its questions, channel, ratings, clone count, and (where shared) its grounding knowledge doc.

render_survey

$ rcs-survey rendersurveys:read

Try-before-you-buy: render with sample variables and inspect the validated interactive RCS payload plus the mandatory SMS fallback.

create_survey

$ rcs-survey createsurveys:write

Author a new survey from a content object. The shared validator rejects anything that breaks channel rules with machine-coded errors.

clone_survey

$ rcs-survey clonemarketplace:clone

Deep-copy a marketplace listing into your org as a clean private draft you fully own — no provenance carried over.

submit_survey

$ rcs-survey submitsurveys:submit

Send a draft to the provider (Twilio) for brand approval and read back its approval status.

send_survey

$ rcs-survey sendsurveys:send

Broadcast an org-owned survey to an E.164 list — RCS-first, with the always-on SMS/MMS fallback. Returns the delivery funnel.

get_results

$ rcs-survey resultsresults:read

Read back collected responses — per-question tallies, completion and response rates, and live analytics — for any survey your org has sent.

get_usage

$ rcs-survey usageusage:read

Read the org's month-to-date metered usage — the same ledger the human dashboard and billing meter count.

The contract

The /api/agent gateway

The HTTP surface every skin wraps. Auth is the agent-key rail (not the human master key); each write is additionally scope-gated. Reads are tenant- and published-scoped, exactly like the human routers.

Method	Path	Scope	Does
GET	/capabilities	any key	Catalog + granted scopes
GET	/surveys	surveys:read	Search the library
GET	/surveys/:id	surveys:read	Fetch one survey
POST	/surveys	surveys:write	Create a draft
POST	/surveys/:id/render	surveys:read	Render + validate
POST	/marketplace/:id/clone	marketplace:clone	Clone into your org
POST	/surveys/:id/submit	surveys:submit	Submit for approval
POST	/surveys/send	surveys:send	Broadcast to recipients
GET	/surveys/:id/results	results:read	Read collected responses
GET	/usage	usage:read	Read metered usage

Identity

Keys are capability tokens

Minted by an admin. An org admin creates a key via POST /api/agent-keys (mint, list, and revoke). A Settings → API Keys tab is on the way.
Shown once, hashed at rest. The rcsk_live_… secret is displayed a single time and stored only as a SHA-256 hash. Lose it and you mint a new one.
Scoped & revocable. Each key carries an explicit scope set and can be revoked instantly. Revocation fails closed; last-used is tracked for audit.
A separate rail. The agent gateway never accepts the human master key, and the human app never accepts an agent key. Two surfaces, never conflated.

Scope vocabulary

surveys:readSearch, fetch, and render surveys
surveys:writeAuthor new survey drafts
surveys:submitSubmit drafts for provider approval
marketplace:cloneClone marketplace listings into your org
surveys:sendBroadcast surveys to recipients
results:readRead collected responses and analytics
usage:readRead metered usage for the org

Skill chains

Packaged multi-step workflows

The value is the chain, not new capability — each skill strings the tools into a repeatable job and declares the least-privilege scope set it needs, so an org can mint a key that matches exactly one workflow.

Find & clone a survey

find-and-clone-survey

Shop the marketplace for the best-fit survey, inspect renders before committing, then clone the winner into your org as a fresh draft.

search → render → clone

surveys:readmarketplace:clone

Author & publish

author-and-publish

Turn a one-line brief into a validated, compliant survey, self-check the render, and submit it for provider approval.

create → render → submit

surveys:writesurveys:readsurveys:submit

Survey in a box

survey-in-a-box

Pick or clone a survey, validate personalization against the recipient list, confirm, send, and report the delivery funnel.

clone → render → send → usage

surveys:readmarketplace:clonesurveys:sendusage:read

Response analyst

response-analyst

Pull a sent survey's collected responses and turn the raw tallies into a grounded, on-brand summary of what respondents are saying.

get_results → analyze (grounded)

results:read

Safety

Hardened for external callers

This is the first surface meant to be hit directly by outside clients, so it's built to refuse anything the human app would. These properties came out of an adversarial code review.

Two rails, never conflated

The agent gateway is a separate surface from the human app. Neither token accepts the other's: an agent key can't reach human admin routes, and the master key isn't honored here.

Approval-gate parity

Agent sends enforce the exact same provider-approval gate as the human send path — there's no back door to ship an unapproved survey.

Smishing containment

Send destinations are E.164-validated and the gateway is rate-limited — per-IP before auth, per-key after, and tighter still on send — to bound abuse.

Keys hashed & revocable

Secrets are shown once, stored only as a SHA-256 hash, scoped, and revocable. Revocation fails closed, and last-used is tracked for audit.

Atomic clone counts

Clone counters increment atomically, so concurrent agent clones never lose an update or race the marketplace ranking.

Send rollback

A send that fails marks its broadcast FAILED rather than leaving it stuck in SENDING — the funnel you read back is always truthful.

Cross-org redaction

Org-private knowledge docs and response data are stripped from cross-org reads of published listings, so grounding content and results never leak between tenants.

One usage ledger

Agent activity writes the same UsageEvent ledger as the human app, so usage, billing, and reporting stay unified across both rails.

Roadmap

Designed next: agent commerce

Fully designed and coming soon — no payment code ships in this release yet. Stated plainly so there's no ambiguity about what's live today.

Coming soon

x402 pay-per-call

An agent-native payment rail: a priced route answers HTTP 402, the agent signs a USDC transfer on Base, and the call proceeds — no account, no checkout. Designed in full; deliberately deferred (no payment code ships yet). The capabilities endpoint already returns pricing: null as the seam.

Coming soon

Priced marketplace & author payouts

One-time clone prices and per-send royalties set by survey authors, with on-ledger payouts — turning the library into a marketplace agents can buy from. Depends on the x402 rail.

FAQ

Agent platform questions

What does "agent-native" mean for RCS Surveys?

An autonomous AI agent can discover, author, clone, render, send, and read the results of RCS surveys programmatically — through one authenticated HTTP gateway (/api/agent/*), with no human clicking buttons. The same gateway is exposed as an MCP server, a CLI, and an embeddable typed client.

How does an agent authenticate?

With a scoped agent API key (prefixed rcsk_live_…), minted by an org admin. The plaintext key is shown once and stored only as a SHA-256 hash. It carries a least-privilege set of scopes and is revocable. The agent gateway is a separate rail from the human app — neither token is accepted on the other's surface.

What can an agent actually do through the gateway?

Ten tools, each one gateway call: capabilities, search_surveys, get_survey, render_survey, create_survey, clone_survey, submit_survey, send_survey, get_results, and get_usage. Each is gated by a scope, so a key only does what it was minted to do.

Which plan do I need to use the MCP server and CLI?

The @rcs-surveys/agent-toolkit — the MCP server (rcs-surveys-mcp) and the CLI (rcs-survey) — is a Pro-plan feature. Free accounts can explore the library and the docs; minting an agent key and running the packaged MCP/CLI surfaces requires Pro. Enterprise includes it too.

How do I add the MCP server to Claude?

Run `claude mcp add rcs-surveys --env RCS_GATEWAY_URL=https://your-server --env RCS_AGENT_KEY=rcsk_live_… -- npx -y @rcs-surveys/agent-toolkit rcs-surveys-mcp`. The tools then appear natively in the agent.

What are skill chains?

Packaged, composable workflows that string the tools into a repeatable job — find-and-clone-survey, author-and-publish, survey-in-a-box, and response-analyst. The value is the chain, not new capability, and each declares the least-privilege scopes it needs.

Can an agent send surveys to anyone it wants?

No. Sends require the surveys:send scope, the survey must be org-owned and provider-approved (the same gate the human path enforces), destinations are E.164-validated, and the gateway is rate-limited. Sending is billable and irreversible, so the send skill confirms first.

Is per-call crypto payment (x402) available yet?

No. The x402 pay-per-call rail is fully designed but intentionally deferred — no payment code ships in this release. Today a scoped key transacts against the org's existing metered billing; the capabilities endpoint exposes pricing: null as the forward-looking seam.

Building an agent on RCS surveys?

Ask for early access to the gateway and toolkit, or tell us what you're wiring up — we'll help you scope the keys.

Early access Talk to us github.com/msg2ai