@rcs-templates/agent-toolkit

Agent skins for the rcs-templates agent gateway (/api/agent/*): an MCP server (rcs-mcp) and a CLI (rcs), sharing one typed gateway client and one declarative tool catalog. Zero runtime dependencies.

Part of the agent-enablement work — see docs/design/AGENT-ENABLEMENT-AND-X402-DESIGN.md. This implements P0–P4 (gateway client, MCP, CLI, skills). The x402 pay-per-call rail (P1/P5) is intentionally not included yet.

The MCP server lets Claude (Claude Code, Claude Desktop, or any MCP host) search, read, render, create, clone, submit, and send RCS templates through your org's gateway — authenticated with one agent key.

Setup (5 minutes)

1. Get an agent key

In the app at https://app.rcs-templates.com: Settings → API keys → Create key (Admin only). Pick the scopes the agent needs, then copy the key — it is shown exactly once (rcsk_live_…). Treat it like a password; you can revoke/rotate it from the same screen.

Scopes: templates:read, templates:write, templates:submit, marketplace:clone, messages:send, usage:read, surveys:read, surveys:write, surveys:submit, surveys:send, results:read.

2. Set the gateway URL

RCS_GATEWAY_URL=https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com

The key is tied to the environment it was minted in — a key from one environment will 401 against another (they're different databases).

3. Run it — published on npm

The package is on the public registry, so the quickest path needs no checkout or build. It ships two bins (rcs and rcs-mcp), so under npx you must select one with -p (the package) followed by the bin name — npx @rcs-templates/agent-toolkit rcs … fails with "could not determine executable to run" because agent-toolkit is not itself a bin:

npx -y -p @rcs-templates/agent-toolkit rcs capabilities

Or install the bins globally and call them directly:

npm i -g @rcs-templates/agent-toolkit
rcs capabilities
rcs-mcp            # stdio MCP server

Monorepo contributors can run from source instead — build once from the root:

pnpm install
pnpm --filter @rcs-templates/agent-toolkit build   # -> dist/mcp.js, dist/cli.js

4. Verify the key works (before wiring up a host)

export RCS_GATEWAY_URL=https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com
export RCS_AGENT_KEY=rcsk_live_…
npx -y -p @rcs-templates/agent-toolkit rcs capabilities

A healthy response lists grantedScopes and the tool catalog. If you get Gateway 401, the key is wrong/rotated or points at the wrong environment.

Add to an MCP host

Claude Code

claude mcp add rcs-templates \
  --env RCS_GATEWAY_URL=https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com \
  --env RCS_AGENT_KEY=rcsk_live_… \
  -- npx -y -p @rcs-templates/agent-toolkit rcs-mcp

Running from a local checkout instead? Swap the launch command for the built path: -- node /ABSOLUTE/PATH/TO/rcs-templates/packages/agent-toolkit/dist/mcp.js (use an absolute path). Confirm with claude mcp list (should show rcs-templates), then ask Claude to “list the rcs-templates tools.”

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) and add:

{
  "mcpServers": {
    "rcs-templates": {
      "command": "npx",
      "args": ["-y", "-p", "@rcs-templates/agent-toolkit", "rcs-mcp"],
      "env": {
        "RCS_GATEWAY_URL": "https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com",
        "RCS_AGENT_KEY": "rcsk_live_…"
      }
    }
  }
}

Restart Claude Desktop. The tools appear under the 🔌 menu. (From a local checkout, set "command": "node" and "args" to the absolute dist/mcp.js path instead.)

Tools exposed

Templates: capabilities, search_templates, get_template, render_template, create_template, clone_template, submit_template, send_message, get_usage. Surveys: search_surveys, get_survey, render_survey, create_survey, clone_survey, submit_survey, send_survey, get_results. Each *:write / *:send tool needs the matching scope on your key.

CLI (rcs)

Same client, same auth — handy for scripts and a quick smoke test. Run it via npx (npx -y -p @rcs-templates/agent-toolkit rcs <cmd>), the global rcs binary, or node dist/cli.js from a checkout — all equivalent:

rcs capabilities
rcs search "appointment reminder" --channel RCS --sort rating
rcs get <id>
rcs render <id> --var firstName=Ada
rcs clone <id>
rcs create --file template.json
rcs send <blueprintId> --to +15551112222 --var firstName=Ada
rcs usage

Config flags override env: --url <gateway> / --key <rcsk_…>. JSON in / JSON out — pipe into jq, wire into CI, or call from a skill.

Troubleshooting

| Symptom | Cause / fix | |---|---| | No agent key configured | RCS_AGENT_KEY not reaching the process — for MCP hosts it must be in the server's env block, not your shell. | | Gateway 401 | Key wrong, revoked, or minted in a different environment than RCS_GATEWAY_URL points at. | | Gateway 403 (scope) | The key lacks the tool's scope — mint a new key with it (scopes are fixed at creation). | | Host shows no tools | Wrong path to dist/mcp.js, or the package wasn't built (pnpm --filter @rcs-templates/agent-toolkit build). | | Empty search results | The org has no published/owned templates yet — clone one from the marketplace first. |

Embed the client

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

const client = GatewayClient.fromEnv(); // reads RCS_GATEWAY_URL + RCS_AGENT_KEY
const { items } = await client.call({
  method: 'GET',
  path: '/templates',
  query: { q: 'promo' }
});