AI Agent Integration

Design a Claude Skill or a custom agent that drives RailCall over MCP. The airlock stays authoritative — the agent can propose, plan, and execute, but every consequential step still lands as a signed receipt.

The trust boundary

The agent is a caller, not a signer. The MCP tools it uses are the same ones a human runs from the shell — approval gates, receipts, and license checks all apply.

The interaction shape

A well-behaved agent always follows the same four steps: discover, propose, dry-run, then request live. The MCP tools listed on the MCP Integration page map directly onto those steps.

railcall_workflow_list — find an existing plan that matches the user's intent.
railcall_workflow_compose — if nothing fits, draft a plan CSV and show the human. Do not execute.
railcall_workflow_run in dry-run mode — surface the returned receipt to the human.
railcall_workflow_run live only after explicit approval. Then quote the signed receipt in the reply.

A Claude Skill spec

Skills package the agent's persona, tools, and guardrails. The block below is a YAML-ish template — copy, replace the italicised bits, and ship. It only references MCP tools that RailCall actually exposes.

yaml

name: railcall-ops
description: >
  Governed operations assistant. Uses RailCall as the ONLY path to
  live systems — no direct API calls, no shell.

mcp_servers:
  railcall:
    command: railcall
    args: ["mcp"]

allowed_tools:
  - railcall_workflow_list
  - railcall_workflow_compose
  - railcall_workflow_run
  - railcall_pending_list

instructions: |
  You are the ops assistant for the team. Every consequential action
  goes through RailCall.

  Rules:
    1. Discover before you propose. Call railcall_workflow_list first.
    2. When composing a new plan, return the CSV to the human. Do NOT
       run it in the same turn.
    3. Always dry-run before live. Quote the returned receipt id.
    4. Never claim success without a signed receipt in the tool output.
    5. If railcall_pending_list has an entry, surface it — do not try
       to approve on the user's behalf.

  Refusals:
    - No live send without explicit user approval in the same session.
    - No credential handling. If a workflow needs an OAuth token, tell
      the human to configure it in Studio → Integrations.

examples:
  - user: "Log a note on the Acme deal."
    steps:
      - list plans, find one matching "hubspot log_note"
      - dry-run it, share the receipt
      - ask "run live?" — only proceed on yes

Custom agent (non-Claude)

Any MCP-capable agent works — Cursor, Windsurf, Zed, or a homegrown client. Wire the client with railcall mcp config <client> and use the same four-step shape above.

What NOT to do

Don't teach the agent to call third-party APIs directly. Bypassing RailCall bypasses the airlock, the license check, and the receipt.
Don't cache or paraphrase receipts. Quote the tool output. Fake receipts are what fake-green audits look like.
Don't grant the agent railcall_workflow_run without an approval loop. Dry-run first, live after.

Verify the agent

Test the agent against a free connector (e.g. sami666/hubspot) before pointing it at anything paid. Then check the Receipts tab in Studio — every action the agent took should be there, signed, with the same timestamps the agent quoted back to the user.