Agents

This page is the plan for an AI agent working on a Scrip integration. Read it first. It is also available as Markdown at https://docs.scrip.dev/agents.md.

​

Connect

Add the hosted MCP server at https://mcp.scrip.dev/mcp. Your client opens Scrip sign-in and stores an OAuth token after you approve access. The server does not accept API keys. See Connect a client. The hosted server is read-only. Anything that changes data goes through the dashboard or the REST API at https://api.scrip.dev/v1, with an API key kept on your server. See Authentication.

​

Orient

Call scrip_get_program_overview. It returns the programs, assets, rule sets, rules, and tiers the connection can see. Read Which endpoints you need before you plan anything. It lists the few calls an app makes as users earn and redeem.

​

Configure

Change rules in this order:

1. Read the live configuration with scrip_get_rule_configuration.
2. Check the draft with scrip_lint_rule_configuration.
3. Build a preview with scrip_plan_rule_configuration. It returns the diff, warnings, and final rule order.
4. Simulate the draft with POST /v1/programs/{programId}/rule-configuration/simulations. Nothing in the live program changes.
5. Show the preview to a person. Apply it with POST /v1/programs/{programId}/rule-configuration/apply only after that person approves.

See Managing rule configuration and Testing.

​

Integrate

Your app sends POST /v1/events for each user action your rules care about. Give each event an idempotency_key built from your own data, such as an order ID. The first event for a new external_id enrolls the participant, so you do not create participants first. Events are asynchronous. POST /v1/events returns 202 when Scrip accepts the event. Rules run afterward. Wait for the event.completed webhook, or poll GET /v1/events/{id}. See Event processing.

​

Verify

Fetch the event with GET /v1/events/{id} and read its status and rule_evaluations. Then read the participant’s balances and history. scrip_explain_event gives the same trace through MCP. When a call fails, match on the error code and look it up in Errors. Quote the request_id when you ask for help.

​

Operate

Use scrip_get_participant_context and scrip_get_group_context to explain a balance. Use scrip_get_rule_configuration_history to see which revision was live at a given time and to preview a rollback. Use scrip_get_program_analytics for activity, liability, and expiration. Check Limits and durations before you batch or retry, and keep your client behind the published rate-limit guidance.

​

Next steps