# ikto MCP tools reference

> Streamable HTTP MCP server `https://iknowthisone.online/mcp`. Auth: OAuth 2.1 or `Authorization: Bearer <key>`.
Same monthly clip quota as the website. Server ikto 1.3.0.

Last generated from the live `tools/list` schemas.

## Connect

- Endpoint: https://iknowthisone.online/mcp
- Human docs: https://iknowthisone.online/developers
- This page: https://iknowthisone.online/developers/mcp.md
- Agent skill: https://iknowthisone.online/agents.md
- Server card: https://iknowthisone.online/.well-known/mcp-server-card.json

## Instructions (also sent on initialize)

IKTO turns a window of a long video (a Twitch or Kick VOD or clip, a public Google Drive, Dropbox, OneDrive or WeTransfer link, YouTube when it is switched on, or another video page) into a vertical 9:16 short with burned-in captions. Call get_account first to see the plan and clips left this month. check_link tells you if a link works before you spend a clip. Use suggest_moments to find strong windows, then create_clip with a start and end in seconds, or create_auto_clips to let IKTO pick and frame the top moments itself (Lite, Pro, Max). Layout, captions, logo position and safe zones default to the user's saved default style, then to auto framing (webcam on top and game below when there is a webcam). create_clip burns the same logo overlay as the website editor (logo, logo_pos, logo_width). logo defaults to the user's saved editor setting if they have one, else none; pass logo=ikto to burn the IKTO mark plus iknowthisone.online. A non-empty hook always burns at the top, below the logo when both are on. get_queue shows what is rendering or waiting; get_history lists every clip the user made. If create_clip answers status rendering, the clip has not failed: call get_clip_status until it is done instead of creating it again. Each clip uses one clip from the same monthly quota as the website. Files are deleted shortly after download, so hand the download_url to the user right away. Full parameter reference: /developers and /developers/mcp.md.

## Sources

Twitch VOD (`twitch.tv/videos/…`): full recording; `start`/`end` are offsets from the VOD start. Twitch clip URL: one already-cut highlight — still clipable, but `suggest_moments` / `create_auto_clips` have little to scan. Kick VOD or clip: same split. Live Twitch/Kick channel: any part streamed so far; offsets count from stream start. Public Google Drive, Dropbox, OneDrive or WeTransfer file. YouTube when the site has it switched on. Other public video pages. https only, max 2000 characters.

## Tools

`get_account`, `suggest_moments`, `create_clip`, `get_clip_status`, `create_auto_clips`, `check_link`, `get_queue`, `get_history`, `list_clips`

## Common errors

- Pass an https link to a Twitch, Kick, or YouTube video. — url missing, not https, too long, or blocked.
- start and end must be numbers of seconds.
- MCP clips are up to 180 seconds. Pick a shorter window, or use the website for long Pro clips.
- Rate limited: 10 clips an hour, shared with the website. Try again later.
- This clip isn’t allowed on your plan. — plus upgrade_url / clips_left when it is a quota or paywall gate.
- logo must be none (no overlay) or ikto (the IKTO mark and iknowthisone.online).
- Unknown tool: <name> — JSON-RPC -32602.
- Unauthorized / 401 — missing, revoked, or unapproved API key or OAuth token.

## `get_account` — Plan and clips left

The signed-in IKTO plan (Free, Lite, Pro, or Max), clips used and left this month, and the export rules for that plan (max height, fps, watermark, hours, parallel exports, auto-pick batch_limit). Free on the website and Free here are the same quota. Does not use a clip. Call this first.

**Quota:** Does not use a clip.

### Parameters

None. Call with `{}`.

### Returns

plan, clips_used_this_month, clips_limit_per_month, clips_left, quota_resets, unlimited, shared_with_website, email_verified, export (max_clip_seconds, max_height, max_fps, watermark, video_hours_per_month, video_hours_used, exports_at_once, batch_limit), upgrade_url, email.

### Example `structuredContent`

```json
{
  "plan": "Pro",
  "clips_used_this_month": 12,
  "clips_limit_per_month": 500,
  "clips_left": 488,
  "quota_resets": "2026-12-01T00:00:00Z",
  "unlimited": false,
  "shared_with_website": true,
  "email_verified": true,
  "export": {
    "max_clip_seconds": 180,
    "max_height": 1080,
    "max_fps": 30,
    "watermark": false,
    "video_hours_per_month": 20.0,
    "video_hours_used": 1.4,
    "exports_at_once": 2,
    "batch_limit": 3
  },
  "upgrade_url": "https://iknowthisone.online/billing",
  "email": "you@example.com"
}
```

### Common errors

- Unauthorized if the key or OAuth token is missing or revoked.

## `suggest_moments` — Find clip-worthy moments

Scan a Twitch, Kick, or YouTube link (chat spikes, loudness, heatmaps) and return suggested windows with start, end, a reason, an optional hook, and a virality estimate. Works on a VOD, a clip URL, or a Twitch/Kick channel that is live now (moments from the stream so far). Rate limit 60 scans an hour. Does not use a clip.

**Quota:** Does not use a clip. Rate limit 60 scans an hour.

### Parameters

| Name | Type | Required | Default | Allowed | Limits | Description |
|---|---|---|---|---|---|---|
| `url` | string | yes | `omit` | — | — | https link. Twitch/Kick VOD (videos/… or /videos/…) or clip URL, a live Twitch/Kick channel, or YouTube when enabled. Clip URLs are a single already-cut moment; VODs are scanned for several. |

### Returns

url, moments[] (start, end, reason, virality, hook, optional hook_flags), uses_a_clip=false.

### Example `structuredContent`

```json
{
  "url": "https://www.twitch.tv/videos/123",
  "moments": [
    {
      "start": 3720.0,
      "end": 3750.0,
      "reason": "chat spike",
      "virality": 81,
      "hook": "He really hit that"
    }
  ],
  "uses_a_clip": false
}
```

### Common errors

- Pass an https link to a Twitch, Kick, or YouTube video.
- Rate limited: 60 scans an hour. Try again later.
- Scan timeout or SuggestError message from the finder.

## `create_clip` — Render a vertical clip

Cut [start, end] seconds from the link, lay it out at 9:16, burn captions and the same logo overlay as the website editor, and return a download URL. Uses 1 clip from this month's quota (the same quota as the website). Up to 180 seconds. Answers within about 45 seconds: either done with a download_url, or status rendering, in which case call get_clip_status (do not call create_clip again). A non-empty hook always burns at the top (below the logo when both are on), including when word-pop captions are on. Layout, captions, logo, logo_pos, logo_width and safe_platform fall back to the user's saved default style from the app. logo itself is none unless that style includes one, or the agent passes ikto.

**Quota:** Uses 1 clip. Window at most 180 seconds. Rate limit 10 clip jobs an hour, shared with the website.

### Parameters

| Name | Type | Required | Default | Allowed | Limits | Description |
|---|---|---|---|---|---|---|
| `url` | string | yes | `omit` | — | — | Video link (https): Twitch or Kick VOD (full recording) or clip URL (already-cut highlight), a Twitch/Kick channel that is live now (any part streamed so far; offsets count from the stream start), public Drive/Dropbox/OneDrive/WeTransfer file, YouTube when enabled, or another video page. Max 2000 characters. |
| `start` | number | yes | `omit` | — | min 0 | Window start, in seconds from the source start (required). |
| `end` | number | yes | `omit` | — | min 0 | Window end, in seconds (required). Must be after start. At most 180 s after start. |
| `layout` | string | optional | `omit` | `auto`, `split`, `full_cam`, `full_screen` | — | auto: IKTO looks at the video and picks (webcam on top and game below when it finds a webcam, the game centred when there is none). split: facecam on top, gameplay below. full_cam: the facecam fills the frame. full_screen: the video fills the frame (center crop). Optional. Leave it out to use the user's saved default style, else auto. |
| `caption_style` | string | optional | `omit` | `bold-white`, `yellow-pop`, `karaoke-cyan`, `word-pop`, `boxed`, `minimal`, `comic`, `neon`, `classic`, `bebas-red`, `off` | — | Caption preset, or off for no captions (a hook still burns). Optional. Leave it out to use the user's saved default style, else bold-white. |
| `caption_language` | string | optional | `omit` | `en`, `es`, `ar` | — | Caption language. Optional. Leave it out for the user's saved default, else en. |
| `hook` | string | optional | `omit` | — | maxLength 80 | Optional title burned at the top for the whole clip, even when word captions exist. Sits below the logo when logo is ikto. Max 80 characters. |
| `tighten` | boolean | optional | `false` | — | — | Remove dead air: pauses over 0.6 s shrink to 0.15 s and lone filler words (um, uh) are cut. Captions follow. Optional, default false. |
| `speed` | number | optional | `1` | `1`, `1.1`, `1.25`, `1.5` | — | Playback speed with pitch kept. Optional, default 1. Quota counts the window you picked, not the shorter result. |
| `logo` | string | optional | `"none"` | `none`, `ikto` | — | Same overlay as the website Logo upload. Optional. Default none (no overlay), or the user's saved editor default if that style includes a logo. Pass ikto to opt in to the bundled IKTO mark plus iknowthisone.online through the existing logo render path. Plan watermarks are separate. |
| `logo_pos` | string | optional | `"top-right"` | `top`, `top-centre`, `top-center`, `top-left`, `top-right`, `bottom` | — | Same slots as the website editor. top / top-centre / top-center are horizontal centre under the TikTok/Reels top safe zone. top-left and top-right sit in the corners. bottom sits above the lower captions. Optional. Leave it out for the user's saved default style, else top-right. |
| `logo_width` | number | optional | `0.28` | — | min 0.12, max 0.5 | Logo width as a fraction of the 720-wide frame (same as the website logo_width range). Optional. Leave it out for the user's saved default, else 0.28. |
| `safe_platform` | string | optional | `"both"` | `tiktok`, `reels`, `both` | — | TikTok/Reels caption safe zones (same as the website). both keeps clear of either app's chrome. Optional. Leave it out for the user's saved default, else both. |

### Returns

status done: clip (title, start, end, seconds, layout, caption_style, download_url, link_expires_in_minutes), clips_left, plan, note. status rendering: progress_percent, message, next_step (call get_clip_status; do not create again). isError result: error sentence plus clips_left / upgrade_url when it is a gate.

### Example `structuredContent`

```json
{
  "status": "done",
  "clip": {
    "title": "Clip",
    "start": 10.0,
    "end": 40.0,
    "seconds": 30.0,
    "layout": "split",
    "caption_style": "yellow-pop",
    "download_url": "https://iknowthisone.online/api/clip/file?token=…",
    "link_expires_in_minutes": 60
  },
  "clips_left": 487,
  "plan": "Pro",
  "note": "The file is deleted from IKTO a few minutes after it is downloaded."
}
```

### Common errors

- Pass an https link to a Twitch, Kick, or YouTube video.
- start and end must be numbers of seconds.
- MCP clips are up to 180 seconds.
- Rate limited: 10 clips an hour, shared with the website.
- logo must be none or ikto.
- That hook text was blocked.
- Plan / quota / YouTube-cap gates with upgrade_url.

## `get_clip_status` — Check the clip that's rendering

Status of this account's latest clip. While it renders this waits up to 45 seconds, then answers rendering (with progress), done (with a fresh download_url), idle (nothing in flight), expired (file already gone), or an error that says why. Does not use a clip.

**Quota:** Does not use a clip. Waits up to 45 seconds while the latest job is rendering.

### Parameters

None. Call with `{}`.

### Returns

Same shapes as create_clip: rendering, done, idle, expired, or an isError result.

### Example `structuredContent`

```json
{
  "status": "rendering",
  "progress_percent": 42.0,
  "message": "Rendering the clip…",
  "next_step": "The clip is still rendering and has not failed. Call get_clip_status (it waits up to 45 seconds) until status is done. Don't call create_clip again for the same window."
}
```

### Common errors

- Export didn’t finish — no playable clip was saved. Try again.
- Render error sentence with clips_left.

## `create_auto_clips` — Auto-pick and make the top moments

Scan a long Twitch, Kick or YouTube video, pick its best moments, and make each one a vertical clip with its own framing (webcam on top and game below when there is a webcam) and the user's default captions. Uses the same logo overlay as create_clip (none unless the user saved a logo, or the agent passes logo=ikto). Lite, Pro and Max only. Uses 1 clip per moment. count is capped by the plan (get_account export.batch_limit: Lite 1, Pro 3, Max 10). Long videos take a few minutes: when the answer is rendering, call get_clip_status until done; the done answer lists every clip.

**Quota:** Lite, Pro, Max only. Uses 1 clip per moment. count capped by export.batch_limit (Lite 1, Pro 3, Max 10). Rate limit 10 clip jobs an hour.

### Parameters

| Name | Type | Required | Default | Allowed | Limits | Description |
|---|---|---|---|---|---|---|
| `url` | string | yes | `omit` | — | — | VOD link (https), or a Twitch/Kick channel that is live now. Clip URLs are a single moment — prefer a VOD for auto-pick. |
| `count` | integer | optional | `omit` | — | min 1, max 10 | How many moments. Optional. Defaults to the plan's most (Lite 1, Pro 3, Max 10). |
| `clip_seconds` | integer | optional | `30` | `15`, `30`, `45`, `60`, `90` | — | Length of each picked window in seconds. Optional, default 30. |
| `caption_style` | string | optional | `omit` | `bold-white`, `yellow-pop`, `karaoke-cyan`, `word-pop`, `boxed`, `minimal`, `comic`, `neon`, `classic`, `bebas-red`, `off` | — | Caption preset, or off. Optional. Leave it out to use the user's default. |
| `caption_language` | string | optional | `omit` | `en`, `es`, `ar` | — | Caption language. Optional. Leave it out for the user's default, else en. |
| `logo` | string | optional | `"none"` | `none`, `ikto` | — | Same as create_clip. Optional. Default none, or the user's saved editor logo if they have one. Pass ikto to opt in. |
| `logo_pos` | string | optional | `"top-right"` | `top`, `top-centre`, `top-center`, `top-left`, `top-right`, `bottom` | — | Same as create_clip. Optional. |
| `logo_width` | number | optional | `0.28` | — | min 0.12, max 0.5 | Same as create_clip. Optional. |
| `safe_platform` | string | optional | `"both"` | `tiktok`, `reels`, `both` | — | Same as create_clip. Optional. |

### Returns

Same job answer as create_clip. When several files finish, clips[] lists every one (best first) plus clip for the first. While scanning, status rendering with a message that names how many moments.

### Example `structuredContent`

```json
{
  "status": "rendering",
  "progress_percent": 5.0,
  "message": "Finding the top 3 moments and framing each one. Long videos take a few minutes.",
  "next_step": "The clip is still rendering and has not failed. Call get_clip_status (it waits up to 45 seconds) until status is done. Don't call create_clip again for the same window."
}
```

### Common errors

- Auto-pick is on Lite, Pro and Max. On Free, use suggest_moments and then create_clip.
- count must be between 1 and <batch_limit> on this plan.
- clip_seconds must be 15, 30, 45, 60 or 90.
- Only N clips left this month. Ask for fewer.

## `check_link` — Check a link before clipping

Is this link clippable? Returns the title, channel, length, thumbnail and platform, whether a channel is live now, or why it won't work. Nothing is downloaded and no clip is used. Rate limit 120 checks an hour.

**Quota:** Does not use a clip. Rate limit 120 checks an hour.

### Parameters

| Name | Type | Required | Default | Allowed | Limits | Description |
|---|---|---|---|---|---|---|
| `url` | string | yes | `omit` | — | — | Video link (https). Twitch/Kick VOD or clip, live channel, Drive/Dropbox/OneDrive/WeTransfer, YouTube when enabled, or another video page. |

### Returns

ok true: platform, label, title, duration, thumb, creator, kind, verified, plus live-now fields when it is a channel. ok false: platform, label, error.

### Example `structuredContent`

```json
{
  "ok": true,
  "platform": "twitch",
  "label": "Twitch",
  "title": "Ranked grind",
  "duration": 14400,
  "thumb": "https://static-cdn.jtvnw.net/…",
  "creator": "streamer",
  "kind": "video",
  "verified": true
}
```

### Common errors

- Pass an https video link.
- Too many checks. Wait a minute and try again.
- Unsafe URL / private host.

## `get_queue` — Clips rendering or waiting

This account's clips that are rendering or waiting in line (with position, wait time and progress), plus the ones finished or failed in the last 6 hours with download links while the files exist. Covers clips started on the website, the phone app and MCP. Does not use a clip.

**Quota:** Does not use a clip.

### Parameters

None. Call with `{}`.

### Returns

active (count still rendering or waiting), jobs[] (state, title, source, progress, wait, optional download_url), next_step.

### Example `structuredContent`

```json
{
  "active": 1,
  "jobs": [
    {
      "state": "queued",
      "title": "Clutch",
      "source": "Twitch",
      "progress": 0
    }
  ],
  "next_step": "Something is still rendering: call get_clip_status to wait for it."
}
```

## `get_history` — Clip history

Every clip this account made, newest first: title, source link, start and end, length, virality and date. Search by title or link. Page with before = the previous answer's next_before. Files are deleted after download, so remake one with create_clip and the same source_url, start and end. Does not use a clip.

**Quota:** Does not use a clip.

### Parameters

| Name | Type | Required | Default | Allowed | Limits | Description |
|---|---|---|---|---|---|---|
| `limit` | integer | optional | `20` | — | min 1, max 50 | Page size. Optional, default 20, max 50. |
| `before` | number | optional | `omit` | — | — | Optional. next_before from the previous page (created_at timestamp). |
| `search` | string | optional | `omit` | — | maxLength 80 | Optional. Words in the title or source link, max 80 characters. |

### Returns

items[] (title, source_url, platform, start, end, seconds, virality, created_at, file), total, next_before, note.

### Example `structuredContent`

```json
{
  "items": [
    {
      "title": "My best play",
      "source_url": "https://www.twitch.tv/videos/9",
      "platform": "twitch",
      "start": 10.0,
      "end": 40.0,
      "seconds": 30.0,
      "virality": 74,
      "created_at": 1730000000.0,
      "file": "ikto"
    }
  ],
  "total": 1,
  "next_before": null,
  "note": "file is ikto while it can still be downloaded (see list_clips), device when it was saved on the user's device, gone when deleted. To make one again, call create_clip with the same source_url, start and end."
}
```

## `list_clips` — Recent clips

Clips still on the server for this account, newest first, with fresh download URLs. Up to 10. Files are removed shortly after their first download, or within 24 hours. Does not use a clip.

**Quota:** Does not use a clip.

### Parameters

None. Call with `{}`.

### Returns

clips[] up to 10: title, created_at, download_url, link_expires_in_minutes. Empty when nothing is still stored.

### Example `structuredContent`

```json
{
  "clips": [
    {
      "title": "Clip",
      "created_at": 1730000000.0,
      "download_url": "https://iknowthisone.online/api/clip/file?token=…",
      "link_expires_in_minutes": 60
    }
  ]
}
```

## Protocol notes

- JSON-RPC 2.0 over POST. `Accept: application/json, text/event-stream`.
- `tools/call` with a `progressToken` may stream `notifications/progress` as SSE, then the result.
- Tool failures that the model should read are `isError: true` results, not JSON-RPC errors.
- create_clip / get_clip_status hold up to 45 seconds; a slow export is `status: rendering`, not a failure.
- Files are deleted shortly after download (link TTL is on each `download_url`). Hand the link to the user immediately.

