Keply for agents

Keply exposes its read and act surface to external AI agents over the Model Context Protocol and a REST API. Point Claude, ChatGPT, or a custom orchestrator at one server URL and it can read account health, find the revenue at risk, push signals, and have Keply draft the save — with a human in the loop by default.

Overview

Three surfaces, one credential:

Authentication

Mint an API key in Settings → Developers & agents. Keys start with kep_, are shown once, and carry a scope:

Pass the key as a bearer token: Authorization: Bearer kep_…. OAuth sign-in (for one-click connector directories) is coming; the key path stays supported.

Connect over MCP

Transport is Streamable HTTP (JSON-RPC 2.0, protocol 2025-06-18). One stable server URL:

Claude / ChatGPT: Settings → Connectors → Add custom connector, paste the URL. Claude Code:

claude mcp add --transport http keply https://kzqlzstchvmuenukcejb.supabase.co/functions/v1/mcp \
  --header "Authorization: Bearer kep_YOUR_KEY"

Any other MCP client that takes a JSON config:

{
  "mcpServers": {
    "keply": {
      "type": "streamable-http",
      "url": "https://kzqlzstchvmuenukcejb.supabase.co/functions/v1/mcp",
      "headers": { "Authorization": "Bearer kep_YOUR_KEY" }
    }
  }
}

List the tools, then call one:

curl -X POST https://kzqlzstchvmuenukcejb.supabase.co/functions/v1/mcp \
  -H "Authorization: Bearer kep_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -X POST https://kzqlzstchvmuenukcejb.supabase.co/functions/v1/mcp \
  -H "Authorization: Bearer kep_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"money_in_play","arguments":{"limit":5}}}'

Tool reference

13 tools. read never modifies anything. write moves data in or creates drafts, but never reaches a customer. actcontacts a customer and obeys the account's autonomy dial. Every tool carries MCP behavioral annotations (readOnlyHint / destructiveHint) that match this table.

REST ingest API

POST /functions/v1/ingest with a batch of events — account, usage, or signal. Accounts are created by domain on the fly; every touched account is re-scored inline. Needs a full-scope key. Full schema in openapi.json.

curl -X POST https://kzqlzstchvmuenukcejb.supabase.co/functions/v1/ingest \
  -H "Authorization: Bearer kep_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"events":[
    {"type":"account","accountDomain":"acme.com","arrCents":1200000,
     "renewalDate":"2026-01-31","seatsContracted":25},
    {"type":"usage","accountDomain":"acme.com","event":"weekly_active","trend":-0.4},
    {"type":"signal","accountDomain":"acme.com","signalType":"ticket",
     "summary":"P1 outage","sentiment":-0.6}
  ]}'

Webhooks

Register an HTTPS endpoint in Settings → Developers & agents → Webhooks and pick events: risk.raised, score.changed, renewal.due. Keply POSTs signed JSON; failed deliveries retry with backoff (up to 6 attempts), and an endpoint that keeps failing is disabled.

POST https://your-app.com/hooks/keply
X-Keply-Event: risk.raised
X-Keply-Delivery: d1f0…
X-Keply-Signature: sha256=<hmac-sha256 of the raw body>

{
  "id": "d1f0…",
  "event": "risk.raised",
  "timestamp": "2026-07-09T12:00:00Z",
  "data": {
    "account": { "id": "…", "name": "Acme", "domain": "acme.com" },
    "reason": "champion_left",
    "severity": "high",
    "arrAtRiskCents": 1200000,
    "detectedAt": "2026-07-09T11:58:00Z"
  }
}

Verify X-Keply-Signature— an HMAC-SHA256 of the raw body keyed by the endpoint's signing secret (shown once at creation):

const crypto = require('crypto');

function verify(secret, rawBody, sig) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Safety & autonomy

• Drafts never auto-send. draft_save / draft_upsell land in a queue for human approval.
• One acting tool. execute_action is the only tool that contacts a customer, and it obeys the per-account autonomy dial (observe → draft → act).
• Least privilege. Read-only keys are refused at every write and send path.
• Audit log. Every agent action is recorded with identity, timestamp, and result.
• Transparent schemas. The tool descriptions your agent receives match this page — no hidden instructions or undisclosed side effects. The MCP only accepts tokens issued for it.

Spec files