Connect an assistant with MCP

MCP lets an assistant inspect RefRef and prepare configuration changes. It does not add referral tracking to your application. Runtime tracking uses your trusted backend and the application integration contract.

This reference describes the current implementation reviewed on 3 October 2026. Local CLI checks are recorded for Claude Code and Codex. Hosted deployment acceptance and other clients need separate validation. Get the correct endpoint from your environment operator; do not assume a public URL is ready.

PrerequisitesCopy Anchor Link

• A RefRef environment with core, API, auth app and Console configured together.
• The exact MCP resource URL, including /mcp, reachable by your client.
• A Console account with current Workspace membership. Configuration requires owner or admin authority.
• A Sandbox Project for the first check. MCP can read accessible Sandbox and Live Projects, so select the environment explicitly.

AuthenticationCopy Anchor Link

The /mcp endpoint accepts OAuth access tokens representing the signed-in Console user. It does not accept Workspace API keys. The backend /v1 API uses separate credentials.

Register the HTTP endpoint in your client's MCP settings and complete its OAuth browser flow. Check the client identity and callback destination before consent. Use these scopes:

Client-specific commands and application workflows live in the Claude Code guide and Codex guide. The Lovable preview remains unverified with RefRef.

Select scope explicitlyCopy Anchor Link

1. Call get_workflow with workflow set to integration, configuration or troubleshooting.
2. Call list_workspaces and select the intended Workspace.
3. Call list_projects with that Workspace and check the returned Project environment.
4. Use the exact Project ID in subsequent operations. The active Console Workspace does not choose scope for the assistant.

Management tools take { "workspaceId": "…", "input": { … } }. The input contains the fields for that tool. Read the discovered tool schema rather than inventing field names.

Review before executionCopy Anchor Link

preview_change supports create_program, update_program, create_benefit_rule and publish_reward_terms. A preview stores the exact command and configuration state, and returns a Console reviewUrl with the Project environment.

A human Workspace owner/admin must open that URL and approve the record in the Console. There is no MCP approval tool. Approval expires 30 minutes after preview. Execution checks the original user, client and OAuth grant, current authority, and the configuration fingerprint.

After approval, the assistant can call execute_change. If a response is lost, retry the same proposal ID: the result and mutation commit together. A stale proposal needs a new preview. A new connection requires a new preview and approval; it does not revive an old proposal.

Creating a Program does not automatically establish every prerequisite for tracking. Check published attribution policy, benefit rules and reward terms for the intended flow.

Verify and disconnectCopy Anchor Link

A useful acceptance record includes discovered Workspace/Project IDs, the selected environment, rejection of an unapproved proposal, human approval, one execution and an identical retry result. Do not record secrets, OAuth tokens or full sensitive request logs.

Use the auth app's /mcp/connections page to disconnect. Previously issued access and refresh tokens must stop working. A client-side configuration removal alone is not the same acceptance check as server-side revocation.

Application integration has a different acceptance target: a captured arrival, accepted Event and preserved referral. Continue with the runtime integration reference.