OperationsPreview · 4 min read

MCP server

Perkamo MCP connects AI clients such as Claude Desktop, Claude Code and Codex to your Perkamo Space. Use it for operator workflows: inspecting program rules, checking customers, preparing migrations and running supervised operational actions.

Do not use MCP as an end-user widget, browser integration or replacement for your production backend.

Hosted MCP with OAuth

Use the hosted endpoint when your AI client supports remote MCP servers:

text

https://api.perkamo.com/mcp

The client opens a browser login and connects to your Perkamo Console account. Access follows your Console permissions and active Space. Viewers can inspect data. Admins and owners can run write operations when the client has write access and the tool call includes confirm: true.

Install in MCP clients

You do not need to install an npm package or create a server API key for hosted MCP.

Claude.ai and Claude Desktop

In Claude.ai or Claude Desktop, add a custom connector:

Open Customize > Connectors.
Choose Add custom connector.
Use this remote MCP server URL:

text

https://api.perkamo.com/mcp

Claude opens Perkamo login when you connect the integration.

For Team and Enterprise workspaces, an owner can add the connector under organization connector settings first. Individual users then connect their own Perkamo account from Customize > Connectors.

Claude Code

In Claude Code, add the hosted remote HTTP server with one command:

bash

claude mcp add --transport http perkamo https://api.perkamo.com/mcp

Then start Claude Code, run /mcp, choose Perkamo and complete the browser login. Add --scope user if you want Perkamo available in every project:

bash

claude mcp add --transport http perkamo --scope user https://api.perkamo.com/mcp

Codex CLI

In Codex CLI, add the hosted Streamable HTTP server and authenticate it:

bash

codex mcp add perkamo --url https://api.perkamo.com/mcp
codex mcp login perkamo --scopes mcp:read,mcp:write

Use a read-only OAuth grant when the agent should only inspect data:

bash

codex mcp login perkamo --scopes mcp:read

Other MCP clients

Use https://api.perkamo.com/mcp as a remote HTTP MCP server URL. If your client does not support remote MCP servers, use the @perkamo/mcp npm adapter.

Tools

Read-only tools:

Tool	Use
`get_program`	Read active rules, wallets, rewards, perks, achievements, boosts and levels.
`get_usage`	Read usage metrics and plan limits.
`get_customer`	Inspect one customer by `userId`.
`search_customers`	Search customers by user id, email, name or external id.
`validate_config_module`	Validate a config payload before upload.
`plan_migration`	Build a migration plan from a competitor or custom loyalty export summary.

Mutating tools:

Tool	Use
`identify_customer`	Create or update trusted customer traits.
`emit_event`	Send one trusted event with a stable `transactionId`.
`batch_events`	Send up to 100 trusted events for retries or migrations.
`redeem_reward`	Redeem a configured reward for a customer.
`create_browser_token`	Mint a short-lived browser or stream token.
`upload_config_module`	Upload a new config version.
`adjust_customer`	Manually adjust customer wallets and unlocked perks.

Mutations

Write operations require write access and confirm: true in the tool input. This prevents an agent from changing rules, emitting events or redeeming rewards just because it inferred an action from context.

Prefer test Spaces for configuration work, migrations and replay tests.

Config changes

validate_config_module validates supported config modules before upload and returns warnings for fields or modules that need manual review. Keep uploads in test Spaces first when you are changing rewards, achievements, boosts or tiering logic.

Stage new config versions for review first. Upload an active version only after inspecting the full program with get_program.

Migrations

Use plan_migration before importing data from Smile.io, Yotpo, LoyaltyLion, Gameball, Talon.One, Voucherify, Open Loyalty or a custom platform. A safe migration usually follows this order:

Export source rules, rewards, point balances, customer ids, issued rewards,

referrals and tier state.

Map source point currencies to Perkamo wallets.
Configure earning rules, rewards, passive perks and levels in a test Space.
Identify a dry-run cohort and replay representative events with deterministic

transaction ids.

Reconcile wallets, unlocks, redemptions and webhooks before production cutover.

Do not send computed point totals, tier names or reward state as event context. Perkamo should compute those from trusted facts, rules and idempotent event history.

Security checklist

Prefer hosted MCP for team usage.
Grant write access only to trusted operators.
Keep mutating MCP sessions short-lived and operator-supervised.
Use deterministic transactionId values for event replay and reward

redemption.

Treat loyalty balances, issued rewards and VIP state as financial-like data;

preserve source exports and reconciliation logs outside MCP.

Review Security and keys before exposing MCP access to a

wider team.

Klaviyo sync brief

Webhooks