MCP · REST · Streamable HTTP

Kordi for Developers

Give your AI agent a memory for subscriptions. Kordi exposes a user's billing state — active subs, trials, price hikes, upcoming bills — through a standard MCP server and a REST provisioning API.

MCP Streamable HTTP 7 Tools 1 Resource Partner Provisioning

Overview

hub

MCP Server

Streamable HTTP at /mcp. Any MCP client — Claude, Raycast, Cursor — can connect with a Bearer token.

push_pin

Proactive Triggers

kordi_list_proactive_tasks returns the agent worklist: trials about to convert and pauses due to resume — sorted most-urgent first.

person_add

Partner Provisioning

Push subscriptions for users who don't have Kordi accounts yet. Shadow account + verify email. Scales with a partner key (1 000/hr).

Quick Start

Step 1 — Get a token

Individual users generate a long-lived token at /token. Partners provisioning multiple users use guest-ingest — tokens are returned in the response.

Step 2 — Call the MCP endpoint

# Preferred: Authorization header (token never hits logs/Referer)
curl -X POST https://kordiapp.com/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Legacy fallback (back-compat only — prefer the header above)
curl -X POST "https://kordiapp.com/mcp?token=<your-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Step 3 — Configure your MCP client

Transport

Streamable HTTP

Server URL

https://kordiapp.com/mcp

Auth header

Authorization: Bearer <token>

Server name

kordi-mcp-server

Authentication

Identity is resolved at the edge — the MCP Durable Object never sees an unauthenticated request. The edge strips any client-supplied identity headers and re-sets them from the server-resolved values.

Preferred

Authorization: Bearer <token>

Does not appear in request logs, Referer headers, or browser history.

Legacy (back-compat)

?token=<token>

Supported for clients that cannot set headers. Treat any query-param token as short-TTL.

Sessions are re-validated against KV once per hour. Tokens from /token TTL 90 days; partner-provisioned tokens TTL 30 days. Revoke a token by deleting session:<token> from KV.

MCP Tools

kordi_list_subscriptions read

Paginated subscription list. Params: offset, limit, include_paused. Sensitive card fields stripped. Truncates at 25k chars.

kordi_analyze_billing_health read

Price-hike detection, dormant service list, billing cluster analysis. Returns health_score 0–100.

kordi_list_proactive_tasks read

The agent worklist — time-sensitive actions: trials about to convert (trial_ending), elapsed pauses (resume_due). Sorted most-urgent first. Param: trial_horizon_days (1–30, default 7).

kordi_get_cancellation_route write-ish

Returns a deep-link to the provider's cancel/account page and records cancellation intent. Call only on explicit user request. service_id must come from kordi_list_subscriptions.

kordi_ingest_subscription write

Push a discovered subscription into Kordi. Dedupes by normalized name (re-call updates amount/bill date). Optional: trial_end_date (ISO YYYY-MM-DD) lights up the proactive-trial loop; card_network (visa | mastercard | amex | discover) feeds the card-network proof layer — only pass when explicitly known, never guessed. Both are enrich-only on re-ingest. Returns a signed 7-day pause link.

kordi_get_analytics read admin

Whole-DB aggregates: users, swipes, like-rate, discovery volume by source. Admin-gated.

kordi_get_top_shows read

Cross-user show-popularity leaderboard. Aggregate only, no PII.

Resource

kordi://subscription-pulse read

Ambient billing snapshot for feeds and background polling. Pull this once per session instead of chaining multiple tool calls — it returns everything an agent needs to decide what to do next.

proactive_tasks — same worklist as the MCP tool
expiring_trials — real trial cards with trialEndDate
upcoming_bills — ordinary bills in next 7 days
next_bill — next chronological bill
price_alerts — detected streaming price changes
savings_potential — lowest active subscription cost

Partner Provisioning

For server-side integrations pushing subscriptions on behalf of users who may not have Kordi accounts yet. A valid x-partner-key unlocks a 1,000/hr budget and source-labeled onboarding emails. An invalid key is a hard 401 — there's no silent fallback.

POST /api/guest-ingest

curl -X POST https://kordiapp.com/api/guest-ingest \
  -H "x-partner-key: <your-partner-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "source": "your-source",
    "subscriptions": [
      {
        "name": "Netflix",
        "amount": 15.99,
        "bill_date": 14,
        "trial_end_date": "2026-07-15",
        "card_network": "visa"
      }
    ]
  }'

Response — new account

"status": "created",
"imported": 1,
"total_monthly": 15.99,
"token": "clerk_reg_...",          // use for MCP calls on behalf of this user
"mcp_url": "https://kordiapp.com/mcp?token=..."

Response — existing account

"status": "existing",
"imported": 1,
"total_monthly": 15.99
// no token — anti-takeover invariant. subs are still imported.

Subscription fields

name string, required
amount number, required (monthly $)
bill_date 1–31 or string, optional
trial_end_date YYYY-MM-DD, optional
card_network visa|mastercard|amex|discover

trial_end_date activates proactive cancel reminders (3d + 1d email), dashboard badge, and surfaces the trial in kordi_list_proactive_tasks. card_network feeds the card-network attribution proof layer — pass it only when the source explicitly knows it (e.g. from a receipt), never guessed. Both are enrich-only on re-ingest: an absent value never clears what's already stored.

Security invariants

  • Token is never returned for an email that already has an account.
  • A partner key only authenticates the source it's paired with — one partner's leaked key cannot impersonate another source.
  • tier is always server-set to free; it is never read from the request.
  • The user receives a source-labeled email to claim their account on kordiapp.com.

Rate Limits

MCP tool calls per session 20 / 60s
Partner provisioning (with x-partner-key) 1 000 / hr per source
Guest-ingest without partner key 5 / hr per IP
List response character cap 25 000 chars (truncated: true)

Over the MCP rate limit, tools return { isError: true } with a back-off message. Page large account lists with offset / limit rather than relying on a single call.

Contact

Partner or integration inquiry

To get a partner key, discuss an integration, or report an issue with the API.

keith@kordiapp.com

Individual users

Connect Kordi to Claude, Raycast, Cursor, or any MCP-compatible client.

Get Your Token →