add_to_knowledge

Tool

add_to_knowledge

Capability: write Rate limit: 60 / hr per token

The MCP surface is read and add only. To update, delete, or organize existing items, use the REST API.

Parameters

Name	Type	Required	Description
`kind`	enum	yes	`url` or `text`
`url`	string	when `kind="url"`	YouTube link, podcast page, RSS-direct .mp3, webpage article, or direct audio URL (mp3, m4a, wav, ogg, flac, aac)
`text`	string	when `kind="text"`	Between 20 and 500,000 characters of raw text to ingest
`title`	string	when `kind="text"`	Between 1 and 500 characters
`in_kb`	boolean	no	Make the item queryable via `search_knowledge_base`. Default `true`.
`auto_transform`	boolean	no	Generate the AI transform at ingest time. Default `false` for agent calls. Chunks still embed for KB search.

kb_only tokens force in_kb=true regardless of what you pass.

Example: URL ingest

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_to_knowledge",
    "arguments": {
      "kind": "url",
      "url": "https://www.youtube.com/watch?v=...",
      "in_kb": true,
      "auto_transform": false
    }
  }
}

Example: text ingest

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_to_knowledge",
    "arguments": {
      "kind": "text",
      "title": "Standup notes 2026-05-19",
      "text": "Decisions: ship the API docs. Folder rename deferred. ..."
    }
  }
}

Response

{
  "status": "ready" | "transcribing",
  "user_item_id": "uuid",
  "content_id": "uuid",
  "folder_id": "uuid or null"
}

status: "ready": content is available now. This is returned for webpages, pasted text, and YouTube videos already cached.
status: "transcribing": the paid transcription pipeline is running. Poll get_item or REST GET /items/{id} until transcription_status === "done".
folder_id is non-null when the token is single-folder-scoped (auto-filed). Multi-folder and whole-library tokens return null. The item is unfiled. Use REST POST /items/{id}/folders to file it.

Scope-size-1 auto-file rule

When the token's folder scope is exactly one folder, new items auto-file into that folder via a server-side join. This supports the common "one Claude Desktop install, one folder, one agent" pattern.

Tokens with multi-folder scope or whole-library scope leave new items unfiled. There is no automatic placement when the destination is ambiguous. The caller can add memberships via REST after ingest:

POST /api/v1/items/{user_item_id}/folders
{ "folder_ids": ["..."] }

Errors

Code	Cause
`-32602`	Missing required field for `kind`, or invalid format
`-32602` (forbidden binary)	Binary uploads are not supported via MCP. Use REST `/api/v1/uploads/*`.
`-32603` (ingest_failed)	URL unreachable or content extraction failed
Quota exceeded (402)	Monthly transcription quota exceeded. Response includes the user's tier and cap.
`-32605` (rate-limited)	Per-token cap exceeded

Cost notes

URL ingest of a previously-cached YouTube video is free (server-side dedupe via contents row sharing).
URL ingest of a new YouTube, podcast, or audio URL hits AssemblyAI or Gladia for transcription. Counts against the user's monthly transcription minutes quota.
Text ingest is free (no transcription).
Embedding and chunking is always run. Embeddings use Voyage voyage-context-3 (contextualized chunk embeddings, 1024-dim), which is inexpensive.
auto_transform=true runs a Claude Sonnet generation per item, approximately $0.10 per item. Defaults to false for agents because agents read chunks, not transforms.

REST /api/v1/ingest: the same shape over plain HTTP. Use this from automation tools that do not speak JSON-RPC.
Binary uploads: the three-step signed-URL flow for audio, video, PDF, and image files.

add_to_knowledge

On this page