> For the complete documentation index, see [llms.txt](https://docs.tiun.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiun.io/guides/agent-integration/agent-integration.md).

# Agent integration

Instead of wiring tiun by hand, you can let your AI coding agent do it. Two pieces make this work well:

* A **skill** — a curated, agent-readable instruction pack that teaches the agent the patterns it should follow when integrating tiun.
* An **MCP server** — a live connection to your my.tiun.business account, so the agent reads your snippet ID, provider, and product list directly instead of asking you to copy-paste them, and can create or edit products for you when you ask it to.

With both in place, you can prompt your agent with something as short as "integrate tiun" and it'll discover the right products, confirm the integration mode, and generate the code.

***

## 1. Install the tiun-sdk skill

A skill adds tiun-specific instructions to your codebase so your agent knows how to integrate tiun correctly — which APIs to call, how to handle login, when to use `userChange` vs. `paywallShow`, etc.

```bash
npx skills add https://mcp.tiun.business
```

This installs the skill into your project where your agent can pick it up automatically. It needs [Node.js](https://nodejs.org/) 18+ for `npx`; the CLI works out which agents you have installed and puts the skill where each one looks for it.

Prefer a different installer? The [tiun-app/skills README](https://github.com/tiun-app/skills#installing) covers the alternatives — `gh skill install tiun-app/skills` via the GitHub CLI, the Claude Code plugin marketplace, a Cursor remote rule, or cloning the repo and copying the skill in by hand.

***

## 2. Connect the MCP server

Add the tiun MCP server to your agent's MCP settings:

```
https://mcp.tiun.business/
```

How you register an MCP server **depends on the agent** — Cursor, Claude Code, and other clients all wire MCP servers in slightly different ways (a config file, a settings panel, a CLI command, etc.). Check your agent's documentation for "MCP" or "Model Context Protocol" to find the exact steps.

### If your agent can't complete browser authentication

Connecting to the tiun MCP requires a browser-based sign-in. Some agents don't support that flow for remote MCP servers — the connection stalls or fails at the login step. If that happens, register the server through [mcp-remote](https://www.npmjs.com/package/mcp-remote) instead: a small local proxy that runs as a command-based (stdio) MCP server, performs the browser sign-in itself, and forwards the connection to `mcp.tiun.business`.

```json
{
  "mcpServers": {
    "tiun": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.tiun.business/"]
    }
  }
}
```

This needs Node.js on your machine. On first connect a browser window opens for the tiun sign-in; after that, tokens are cached and refreshed automatically. Nearly every agent supports command-based MCP servers, so this works even where native remote authentication doesn't — as long as the machine has a browser. If your agent connects to `https://mcp.tiun.business/` directly without trouble (Claude Code and Cursor do), you don't need this.

Once connected, the agent can read your providers, snippet IDs, and products in real time. The tiun-sdk skill detects the MCP and uses it automatically — so when you ask the agent to integrate, it pulls data from your account instead of relying on what you paste in.

### What the agent can do through MCP

**Read** — your providers and their snippet IDs, the product catalog for either environment, and the tax categories a product can be filed under.

**Write** — create and edit one-time and subscription products, so you can say "add a Pro plan at €9.90 a month" instead of switching to the dashboard mid-integration.

Writes are constrained on purpose:

* The agent must show you the exact change — name, price, interval, tax category, environment — and get your explicit go-ahead before it calls anything.
* It defaults to **sandbox**. Writing to live is a deliberate choice you have to make, and the agent is instructed to say so in its confirmation.
* Prices and names come from you or from values already written down in your project. The agent is instructed to ask rather than guess an amount.
* **Time-based products can't be created or edited through MCP** — those stay in the dashboard.
* **Nothing can be deleted, archived, or deactivated through MCP.** There's no undo for a write, so read the confirmation before you approve it.
* **A product whose tax category is "Something else" has to be created in the dashboard.** That option is part of the dashboard's new-product form and is not offered over MCP, so an agent cannot select it. When none of the real categories fit your product, the agent should stop and hand the step back to you.

{% hint style="info" %}
A product's **tax category is permanent** — no tool can change it after creation. If the agent proposes one that looks wrong, correct it before you approve the create. See [Products](/reference/generic/products.md).
{% endhint %}

**Sandbox and live are separate environments** with their own snippet IDs and product IDs. MCP returns both (each provider is tagged sandbox or live). If you have products set up in sandbox and in live, the agent can pick the right IDs for the environment you're building against — sandbox while you're developing (`sandbox: true`), live when you're shipping production traffic.

This step is optional, but recommended: without MCP the agent has no view of your dashboard and you'll have to hand it the snippet ID and product IDs yourself.

See [Sandbox](/reference/generic/sandbox.md) for how the two environments relate.

***

## 3. Prompt your agent

You're ready. Open your agent in your project and ask it to integrate tiun. Examples:

* **General** — "Integrate tiun." The agent will ask which integration mode (subscription, one-time purchase, time-based, or a combination), which products to wire, and any routes to gate.
* **Specific** — "Set up a subscription paywall on the `/premium` route using my Pro plan." The agent will confirm the product ID via the MCP and write the integration.
* **One-time** — "Add a buy button for my lifetime license and unlock the `/pro-tools` route once it's purchased."
* **Time-based** — "Add a time-based paywall to the article view and meter content on route changes."
* **Create a product** — "Create a Pro subscription at €9.90 a month in sandbox, then wire it up." The agent will confirm the name, price, interval, tax category, and environment with you before it creates anything.

Before writing code, the agent will confirm the integration mode, the product(s) to use, and the gating points — so nothing is wired silently.

***

## Available skills

The tiun-sdk skill is one of several maintained skills. The full list lives at [tiun-app/skills](https://github.com/tiun-app/skills) on GitHub.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tiun.io/guides/agent-integration/agent-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.