OperationsPreview · 8 min read

MCP connections

Connect AI clients through hosted OAuth or the Space-scoped @perkamo/mcp npm adapter.

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.

Choose how to connect

Both options connect MCP clients to Perkamo, with capabilities determined by their authentication model:

Option	Authentication	Capability	Best for
Hosted MCP	Perkamo Console OAuth	Full user-authorized toolset across every accessible Space.	Managed remote MCP, teams and multi-Space operations.
npm adapter	Space server API key	Core program, customer, event, reward and config tools for the keyed Space.	Local stdio clients and controlled private bridges.

Start with hosted MCP when the client supports remote HTTP servers. Choose the npm adapter when the client expects a local command, your environment requires stdio, or you operate a private bridge.

Hosted MCP (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. Perkamo shows the client name, callback host and requested scopes before you authorize the connection. Access follows your Console permissions across every Space you can access. The Space selected during sign-in is only the default: tools accept an explicit spaceId, so an agent can inspect or copy between Spaces without changing your browser session or asking you to sign in again.

Viewers can inspect data. Admins and owners can run write operations when the OAuth grant includes mcp:write. Test Space work does not require repetitive confirmation. Every Live Space mutation requires confirmProduction: true after the user reviews the named target Space.

The final loopback callback page, if your MCP client uses one, is rendered by that client. Perkamo controls and brands the Perkamo login and authorization pages, but cannot restyle another application's local “authentication complete” page.

Connect hosted 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

Reconnect with write access only for an operator-supervised change:

bash

codex mcp login perkamo --scopes mcp:read,mcp:write

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.

Local MCP adapter (npm)

@perkamo/mcp is the installable MCP adapter for clients that launch a local stdio command. It connects to the hosted Perkamo API using a server API key; the installation only launches the adapter process.

Install the package globally with Node.js 22 or newer:

bash

npm install --global @perkamo/mcp

Create a server API key for the intended Test or Live Space, then configure the MCP client to launch perkamo-mcp. A common stdio configuration looks like:

json

{
  "mcpServers": {
    "perkamo": {
      "command": "perkamo-mcp",
      "env": {
        "PERKAMO_SERVER_API_KEY": "sk_test_..."
      }
    }
  }
}

MCP client configuration formats vary, but the command and environment variable are the same. Keep the configuration file out of source control or use the client's secret store.

The npm adapter is intentionally Space-scoped because a server API key belongs to one Space. To work across all Spaces available to one Console user, use hosted OAuth MCP.

With server-key authentication, the adapter supports program and usage reads, customer lookup, trusted event ingestion, reward redemption, manual customer adjustments, local config validation and full-module config upload for the keyed Space. Organization discovery, cross-Space copying, entity duplication, whole-program validation, event simulation, transaction receipts and customer ledger reads require hosted OAuth.

The adapter is read-only by default. To enable mutations, explicitly set PERKAMO_MCP_ALLOW_MUTATIONS=true in its environment. The server key must also have the specific API scope required by the operation. A Live Space mutation still requires confirmProduction: true after the user reviews the target.

See the npm package for the current version and packaged README.

Tools

The full hosted OAuth toolset is listed below. The npm adapter exposes only the Space-scoped subset described in Local MCP adapter (npm).

Discovery and read-only tools:

Tool	Use
`get_connection_status`, `whoami`, `get_current_space`	Inspect auth mode, user, scopes, expiry and default Space.
`list_organizations`, `list_spaces`, `get_space`	Discover accessible Spaces with IDs, roles and Test/Live environment.
`get_program`, `get_usage`	Read program configuration, usage and plan limits for an explicit Space.
`get_customer`, `search_customers`, `get_customer_ledger`	Inspect customer state and authoritative wallet ledger entries.
`get_transaction`	Read the receipt for one idempotent transaction.
`get_config_schema`, `get_config_module`	Read supported JSON Schema, examples and current module configuration.
`validate_config_module`, `validate_program`	Validate one module locally or proposed modules together with cross-module dependencies.
`list_config_versions`, `diff_config_versions`	Inspect revision history and exact JSON-path changes.
`get_program_copy_options`, `plan_copy_program`	Select whole modules or individual rules and preview a checksummed copy plan.
`plan_duplicate_program_entity`	Preview a non-overwriting duplicate of one program entity in the same or another Space.
`simulate_event`	Evaluate an event without changing customer state.
`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`, `batch_events`	Send trusted events with stable transaction IDs.
`redeem_reward`	Redeem a configured reward for a customer.
`upsert_earning_rule`	Dry-run, review and safely apply one event-to-wallet earning rule without replacing the whole module.
`upload_config_module`	Advanced full-module config upload.
`adjust_customer`	Manually adjust customer wallets and unlocked perks.
`apply_copy_plan`	Apply a reviewed copy plan only while source and target checksums still match.
`apply_duplicate_program_entity`	Duplicate one reviewed wallet, earning rule, reward, passive perk or achievement. Account admin or owner access is required.
`rollback_config`	Reactivate a reviewed prior config version with optimistic locking and whole-program validation.
`copy_program_between_spaces`	Legacy direct copy. Prefer `plan_copy_program` and `apply_copy_plan`.

Mutations

Hosted OAuth write operations require mcp:write. The npm adapter instead requires PERKAMO_MCP_ALLOW_MUTATIONS=true plus the operation's server-key API scope. A Live Space additionally requires confirmProduction: true in the tool input after explicit user approval. The error names the Live Space so the agent can ask one focused confirmation. Routine Test Space work does not repeatedly interrupt the workflow.

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

Config changes

validate_config_module validates one supported config module before upload. validate_program combines proposed modules with the current Space and catches cross-module references such as an earning rule that points to a missing wallet. 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.

For Space copies, call list_spaces, then get_program_copy_options, plan_copy_program and apply_copy_plan. A plan includes the exact diff, source and target checksums, dependency validation, expiry, impact and rollback guidance. If either Space changes before apply, Perkamo refuses the stale plan. The events module means event definitions and earning rules; historical event records are never copied. Source and target must belong to the same Perkamo account, and the connected user must be an account admin or owner.

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 and multi-Space usage.
Use the npm adapter when a client requires stdio or a controlled private

bridge.

Give the npm adapter a dedicated Space server key with only the scopes its

tools need. Rotate or revoke the key when the integration is retired.

Keep server keys in an MCP client's secret store, never in prompts, chat

messages, source control or browser code.

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.

Segment integration

Webhooks