# Kordi MCP Server

[![smithery badge](https://smithery.ai/badge/hello-60oz/kordi)](https://smithery.ai/servers/hello-60oz/kordi)

> Track, analyze, and act on your streaming & SaaS subscriptions — from any AI agent.

**Kordi** is a subscription intelligence platform. This [Model Context Protocol](https://modelcontextprotocol.io) server lets any MCP-speaking AI client — Claude Desktop, Cursor, Raycast, or your own agent — read a user's tracked subscriptions, score their billing health, surface savings, generate cancel/pause links, and push newly discovered subscriptions in.

It's a **hosted, remote** MCP server. There's nothing to install or run locally — you connect to a URL with a token.

- **Endpoint:** `https://kordiapp.com/mcp`
- **Transport:** Streamable HTTP
- **Auth:** `Authorization: Bearer <token>`
- **Registry:** [`com.kordiapp/kordi-mcp-server`](https://registry.modelcontextprotocol.io/v0/servers?search=kordi) on the official MCP Registry
- **Docs:** [kordiapp.com/developers](https://kordiapp.com/developers)

---

## Quick start

### 1. Get a token

Sign in at **[kordiapp.com](https://kordiapp.com)** and generate an API token at **[kordiapp.com/token](https://kordiapp.com/token?ref=github)**. Tokens are valid for **90 days** and grant read/write access to *your own* subscriptions only.

### 2. Connect your client

**Claude Desktop** — add this to your `claude_desktop_config.json` (see [`examples/`](./examples/claude_desktop_config.json)):

```json
{
  "mcpServers": {
    "kordi": {
      "type": "streamable-http",
      "url": "https://kordiapp.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```

**Any client / raw HTTP** — pass the token as a Bearer header (preferred — it never lands in logs, Referer, or history):

```bash
# List the available tools
curl -X POST "https://kordiapp.com/mcp" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

> A legacy `?token=<token>` query-string form is also accepted for back-compat, but prefer the header.

### 3. Ask away

> *"What am I paying for each month?"*
> *"Which subscriptions could I pause to save money?"*
> *"Do I have any price hikes or trials ending soon?"*
> *"I just signed up for Apple TV+ at $9.99/mo — track it."*

---

## Tools

| Tool | What it does |
|---|---|
| **`kordi_list_subscriptions`** | List the user's tracked subscriptions. Paginated (`offset`/`limit`), optional `include_paused`. Sensitive card fields are never returned. |
| **`kordi_analyze_billing_health`** | Score billing health 0–100: price hikes vs. market, dormant services, savings potential, billing-date clustering. |
| **`kordi_get_cancellation_route`** | Generate a deep link to cancel or pause a service, and record the intent. Call only on explicit user request. |
| **`kordi_ingest_subscription`** | Push a discovered subscription into Kordi (used by discovery sources like email/on-screen agents). Dedupes by name; returns a signed pause link. |
| **`kordi_get_top_shows`** | Most-swiped / most-liked shows across all Kordi users. Aggregate only, no PII. |

Plus a resource:

| Resource | URI | What it is |
|---|---|---|
| **`subscription-pulse`** | `kordi://subscription-pulse` | A proactive billing-health snapshot (expiring trials, next bill, monthly spend, savings, price alerts) for ambient feeds. |

> A platform-analytics tool (`kordi_get_analytics`) also exists but is restricted to administrators.

### Tool detail

<details>
<summary><b>kordi_list_subscriptions</b> — read</summary>

**Args**
- `include_paused` (boolean, default `false`) — include paused subscriptions
- `offset` (number, default `0`) — pagination start
- `limit` (number, 1–100, default `50`) — page size

**Returns**
```json
{
  "subscriptions": [ { "id": "netflix", "name": "Netflix", "price": 15.99, "billingDate": 12, "state": "ACTIVE" } ],
  "count": 1,
  "total_count": 1,
  "offset": 0,
  "limit": 50,
  "has_more": false,
  "total_monthly": 15.99
}
```
</details>

<details>
<summary><b>kordi_analyze_billing_health</b> — read</summary>

Takes no arguments. Returns total monthly spend, active/paused counts, `price_hikes`, `unused_services`, `savings_potential`, `top_savings_candidate`, `billing_clusters`, and a `health_score` (0–100, higher is healthier).
</details>

<details>
<summary><b>kordi_get_cancellation_route</b> — action</summary>

**Args**
- `service_id` (string, required) — the exact `id` from `kordi_list_subscriptions`
- `reason` (`too_expensive` | `not_using` | `switching_service` | `finished_content`, optional)

Returns `{ "success": true, "service": "Netflix", "cancellation_url": "https://…" }`. Call only when the user explicitly asks to cancel or pause.
</details>

<details>
<summary><b>kordi_ingest_subscription</b> — write</summary>

**Args**
- `name` (string, required) — e.g. `"Disney+"`
- `amount` (number, required) — monthly amount in USD
- `bill_date` (number 1–31, or ISO date string) — billing day or date
- `source` (`qira` | `screenpipe` | `manual`, optional) — discovery-source attribution

Dedupes by name (re-calling updates amount/bill date). Returns `{ status, subscription, pause_link, dashboard_url }`.
</details>

<details>
<summary><b>kordi_get_top_shows</b> — read</summary>

**Args**
- `limit` (number, 1–50, default `10`)
- `sort_by` (`swipes` | `likes` | `like_rate`, default `swipes`)

Returns a cross-user popularity leaderboard. Aggregate only — no per-user data.
</details>

---

## Auth & identity model

- Your token resolves server-side to your Kordi account. Every tool call is **scoped to your account** — you can only ever see and act on your own subscriptions.
- Identity is bound once per session at the edge; a session cannot be re-bound to a different user mid-stream.
- Sensitive card fields (PAN, CVV, expiry, raw token) are **stripped** from every response — they never leave the server.
- Tokens are short-to-medium-lived (90 days). Treat them as secrets. You can rotate at [kordiapp.com/token](https://kordiapp.com/token?ref=github) at any time.

## Limits

- **Rate limit:** 20 tool calls per 60 seconds per session. Over the limit, tools return a back-off message instead of hitting the database — your agent should wait, not retry-loop.
- **Response size:** large list responses are capped (~25k chars); page with `offset`/`limit` for big accounts.
- **Pause/cancel links** are signed and expire after 7 days.

---

## For integration partners

Discovery sources (email-intelligence agents, on-screen detection pipes, etc.) can push subscriptions into a user's Kordi account via `kordi_ingest_subscription`, or provision brand-new users via the public `POST /api/guest-ingest` endpoint. See [kordiapp.com/developers](https://kordiapp.com/developers) for the partner provisioning flow, source attribution, and the `x-partner-key` model.

## Links

- **Web app:** [kordiapp.com](https://kordiapp.com)
- **Developer docs:** [kordiapp.com/developers](https://kordiapp.com/developers)
- **Get a token:** [kordiapp.com/token](https://kordiapp.com/token?ref=github)
- **MCP Registry listing:** [`com.kordiapp/kordi-mcp-server`](https://registry.modelcontextprotocol.io/v0/servers?search=kordi)
- **Model Context Protocol:** [modelcontextprotocol.io](https://modelcontextprotocol.io)

## License

Documentation and the registry manifest in this repository are released under the [MIT License](./LICENSE). The Kordi server, brand, and backend are proprietary; this repo does not contain server source code.