SDK, REST, CLI, and MCP

OfferKit defines its contract once and exposes it through several interfaces. They share the same resources, authentication model, and business behavior; choose based on where the caller runs and how it should be operated.

TypeScript SDK

Use the SDK in a trusted TypeScript server:

pnpm add @offerkit/sdk

import { createClient, verifyWebhook } from "@offerkit/sdk";

export const offerkit = createClient({
  baseUrl: process.env.OFFERKIT_API_URL!,
  apiKey: process.env.OFFERKIT_API_KEY!,
});

Types flow from the oRPC contract without a code-generation step. The client is safe for edge runtimes; verifyWebhook uses Node crypto only when that helper is imported and used.

The SDK follows nested resource paths:

await offerkit.vouchers.validate(...);
await offerkit.promotions.qualify(...);
await offerkit.loyalty.members.earn(...);
await offerkit.referrals.convert(...);

REST API

Use REST from any backend language. Send:

Authorization: Bearer <api-key>
Content-Type: application/json

Routes are served under /api/v1. The current deployment exposes an OpenAPI 3.1 document at /api/openapi.json, which is the authoritative route and schema inventory for that running version.

CLI

Use the CLI for operator scripts, diagnostics, and back-office work:

pnpm add -g @offerkit/cli
offerkit login --url https://offerkit.example.com --api-key offerkit_…

offerkit vouchers list
offerkit vouchers validate WELCOME10 --amount 5000
offerkit vouchers redeem WELCOME10 --amount 5000 --idempotency-key order-42
offerkit customers list --search alice

Login writes ~/.offerkitrc with mode 0600. OFFERKIT_API_URL and OFFERKIT_API_KEY environment variables override file configuration. Avoid placing a production key in shared shell history or CI logs.

MCP server

For a hosted deployment, enable the OAuth-protected Streamable HTTP endpoint:

OFFERKIT_MCP_ENABLED=true
OFFERKIT_PUBLIC_URL=https://offerkit.example.com

The canonical endpoint is https://offerkit.example.com/mcp. Configure Codex with:

codex mcp add offerkit --url https://offerkit.example.com/mcp
codex mcp login offerkit

Configure Claude Code with the following command, then run /mcp and complete the browser sign-in:

claude mcp add --transport http offerkit https://offerkit.example.com/mcp

The OAuth grant uses the signed-in OfferKit user’s role and can be revoked under Settings → Agent connections.

For a local stdio process using an API key, configure the published package instead:

{
  "mcpServers": {
    "offerkit": {
      "command": "npx",
      "args": ["-y", "@offerkit/mcp"],
      "env": {
        "OFFERKIT_API_URL": "https://offerkit.example.com",
        "OFFERKIT_API_KEY": "offerkit_…"
      }
    }
  }
}

Tool names follow SDK paths with underscores, such as vouchers_validate and referrals_convert. Contract metadata marks tools as safe, mutating, or destructive and adds confirmation guidance to state-changing operations.

Grant a local MCP process a scoped key appropriate for the intended agent tasks. Risk labels help a host present confirmation; they do not replace API authorization.

Which one should I use?

Do not call the SDK or REST API directly from an untrusted browser or mobile client.