Connect an AI assistant

Use Training and Marketing video tools through one Knowlify connector

This guide describes the OAuth connection update. Your MCP service and Knowlify app must both run that update. An older connector that asks for an apiKey still uses the previous setup.

MCP lets an AI assistant call Knowlify Training and Marketing video tools through one connector. With the OAuth connection, you sign in to Knowlify and approve access once. You do not paste an API key into a chat.

Connect

1. Add one connector named Knowlify with the remote MCP URL supplied by your administrator. It ends in /mcp.
2. Choose OAuth authentication and click Connect. If an older entry uses no authentication, remove it and add it again.
3. Sign in on Knowlify. Check the client name, return address, and personal account on the approval page.
4. Approve Training, Marketing videos, or Training and Marketing video access only if you started this connection. Both categories use the same connector.
5. Ask your assistant: “List the available Knowlify Training styles and voices.”

If Claude retains an older Training-only tool list after reconnecting and refreshing tools, remove that entry and replace it with the same URL ending in /mcp?v=0.6.0. This forces fresh discovery while keeping one connector. Start a new chat after reconnecting.

The current test service URL is https://knowlify-mcp-production.up.railway.app/mcp. Its hostname does not identify which API environment it uses. Your administrator configures that separately.

Do not put your Knowlify API key into the connector URL, chat, or an OAuth client-secret field. The client discovers the sign-in flow automatically.

Client setup

Codex

codex mcp add knowlify --url https://knowlify-mcp-production.up.railway.app/mcp
codex mcp login knowlify

The add command may start sign-in automatically; if it does, a second login is unnecessary. Approve the request while the terminal is waiting. If the callback expires, run login again and use the new request. Start a new session to load the connector. Codex CLI receives tool results and links; it must poll status explicitly instead of displaying the HTML player.

For noninteractive codex exec runs, read-only tools can succeed while creation and editing are blocked by the client’s approval policy. Use an interactive approval flow, or --approve-for-me for explicitly authorized automation so Codex’s approval reviewer can evaluate each operation. Do not disable the sandbox or bypass approvals to make a test pass.

The tested Codex desktop installation has MCP Apps disabled (enable_mcp_apps is an under-development feature). MCP 0.6.9 supports presentation: "link" on video and edit status tools to return only readable progress or a Watch video link, without JSON, internal instructions, or an MP4 resource preview. Codex tool instructions request this mode. Shared connectors may advertise player capabilities even when Codex cannot display them, so explicit link mode is more reliable than client detection. Existing player behavior remains available to other clients. Historical tool output is unchanged; ask for a fresh status with link-only presentation.

Claude Code

claude mcp add --transport http --scope user knowlify https://knowlify-mcp-production.up.railway.app/mcp
claude mcp login knowlify

Claude Code also needs its own working Anthropic subscription or API billing. This is separate from Knowlify authorization. Native desktop callbacks are supported by Knowlify MCP 0.6.1 and later.

Cursor

Add a remote MCP server in Cursor’s settings and authenticate it. Alternatively, merge this entry into your existing user MCP configuration, preserving other servers:

{
  "mcpServers": {
    "knowlify": {
      "url": "https://knowlify-mcp-production.up.railway.app/mcp"
    }
  }
}

Enable Knowlify for the chat being tested. Cursor compatibility requires MCP 0.6.4 for its callback registration and 0.6.5 for Marketing player refresh routing. Inline player availability depends on the client surface; video links remain the fallback.

If Cursor asks “MCP App wants to call” get_video_status or get_marketing_video_status, choose Approve this tool to permit that read-only status tool. Automatic player updates cannot proceed while this permission is pending. Server-wide approval also covers other tools, including operations that edit videos or use credits, so it is not required for this check. Open the tool activity to see the player, then click Play when it is ready.

ChatGPT

Your account/workspace must permit custom remote MCP apps. If Developer mode is required, keep CSP enforcement enabled. In the tested web interface, open Plugins → Create app, enter the Knowlify server URL, and choose OAuth. Leave optional OAuth client credentials empty for automatic registration. Complete Knowlify approval, then select Try in chat.

Developer mode installs an unreviewed app for testing; it does not publish Knowlify in the public directory. Availability and administrator controls vary. The same connection supports both video categories.

What you allow

The connection can create Training videos, retrieve video links, edit videos, undo eligible edits, and change narration voices. It can read styles, curated and personal custom voices, and website branding. Video work can consume your account credits.

This release supports your personal workspace. It includes older videos without a saved category that appear in Training history. Organization workspaces are outside this connection’s scope. Marketing videos require explicit permission within the same connector; see Marketing videos. Existing Training connections remain Training-only. Your account must have API access.

Chat-history access requires the additional chat_history permission introduced in MCP 0.8.0. Reconnect and approve it to find past Knowlify chats by topic. Existing video-only grants remain unchanged. See Find past video chats.

Training tools

Tool	Use
generate_videos	Create one to three Training videos with individual controls
generate_video	Create a Training video with duration, style, branding, voice, and cinematic percentage controls
get_video_status	Check generation or voice-change status and obtain the video link
edit_video	Submit an editing instruction
get_edit_status	Check the edit and whether its rendered video was synced
revert_edit	Undo the newest eligible edit
get_brand_kit	Look up branding from a website
list_styles	Find available Training styles
list_voices	Find available voices
change_video_voice	Change narration for all or selected supported scenes

The same connector also exposes 21 Marketing video tools, plus four chat-history tools, for 40 tools total. Visibility in a tool list does not grant permission: each call checks the approved category.

For example: “Create a 30-second workplace safety Training video. Request a 50/50 blend of cinematic scenes and Remotion infographics. Look up knowlify.com branding and apply its selected colors, fonts and logo. Show me the video when it finishes.”

The cinematic percentage is a planning target, not an exact timing guarantee. Creation and editing are asynchronous. Compatible embedded players show one card per accepted video and check progress automatically while visible. Checks run at least 15 seconds apart per video, with at most 20 checks per minute per player. They pause after 30 minutes, on errors, or when the video needs user action. Refresh resumes paused checks. Other clients must poll until the video completes; a job ID alone is not a finished video.

Reopening a saved completed card triggers one automatic status read to recover expired links and reflect later edits. A media-load failure schedules one bounded retry. Repeated failures leave the Refresh and Open video fallback. Playback requires clicking Play; the player cannot notify you while its chat is closed. Older chats may cache an earlier player; refresh the connector tool catalog and use a new tool call to load the current player.

If the client shows “Unable to reach Knowlify” instead of the player, inspect the tool result separately. A completed status with video_url can still be opened even when the client cannot load the embed. A blank or failed embed is not an active automatic poller. Ask for the returned video link as a fallback, and report the client display error. See the current verification results.

Disconnect or reconnect

In Knowlify, open Developer → Manage video connections. Click Disconnect beside the client to stop future requests. Work already submitted can still finish.

Connections expire after 30 days. Clients refresh their short-lived access tokens automatically until then. Reconnect if your connection expires, you revoke its underlying API key, or the client reports that authorization is required.

If the assistant asks for an API key, check that the server has the OAuth update and recreate the connector so it reloads authentication and tool definitions. See Testing and availability for the underlying Training API.

Use saved products and branding

With Marketing access, ask naturally: “Find my saved Nike Air Force 1 product and our saved branding.” The connector searches the same personal Products and Brand libraries as the app. You do not need IDs or a second connector. The assistant reads matching items and asks which one only if several names match. Creating a video remains a separate operation that uses credits.

Saved-library tools require MCP 0.7.0 and the corresponding API routes. Refresh a cached connector catalog if they are missing. Connector instructions prefer supported tools over browser automation, but the assistant host controls discovery and tool selection.

Codex chooses the browser instead of Knowlify

A successful connection does not guarantee the assistant will select it. If Codex opens the website for a supported Knowlify video request, the reusable knowlify-video skill adds guidance at skill discovery, before tool selection. Install that folder under ~/.codex/skills/ and leave automatic invocation enabled. It uses your existing Knowlify connection and does not require another sign-in or connector.

The skill directs requests such as “Access Knowlify and make a UGC video for my Nike Air Force 1 product” to saved-product lookup and the Marketing generation tool. If the tools are unavailable, it reports the connection issue rather than silently using the browser. Explicit browser requests remain supported. A desktop retest confirmed product lookup through the connector in a chat that previously selected computer use. Other assistant hosts control their own discovery behavior.

Updating an existing connection

If Knowlify says “Your Knowlify connection needs updating,” refresh the existing Knowlify connection in your AI app and start a new chat. If the tools are still missing, reconnect that same connection using the same /mcp URL. Sign in and approve the access you need. Do not install a second connector or paste an API key into chat. Existing grants keep their permissions; requesting Marketing or chat history access requires explicit approval.

The read-only check_knowlify_connection tool can compare the tool names actually visible to the assistant with the product tools expected by the service. When no list is supplied it reports discovery state as unknown, rather than claiming the client is current.

MCP 0.9.0 blocks Marketing generation from an old generation contract before submitting jobs or charging generation credits. Current calls include generationContractVersion: 2 and productContext: use saved_product with the retrieved productId for a requested product, or no_product only for a request without a product. A missing product ID in a saved-product call blocks the entire batch. Never use no_product to bypass an unavailable lookup. The server can validate submitted fields, but cannot see the user’s original host conversation to detect an assistant that misstates their intent.

On detecting an outdated generation contract, the server publishes a tool-list change notification, throttled to once per ten seconds, to modern MCP subscriptions that opted in. HTTP responses also prevent storage by HTTP caches. Legacy stateless clients cannot receive unsolicited refresh notifications, and clients control their own tool catalogs and reconnect UI. These measures cannot force an already-open chat to load new tools. Refresh or reconnect remains the fallback; no direct reconnect link is invented because the action belongs to the AI client.

Choose an actor or avatar

Marketing videos with a person use the existing Person library. Ask for a named actor or describe a look, such as “a blonde woman from our library.” The assistant searches list_marketing_actors, reads the selected look with get_marketing_actor, and supplies actorId with personMode: "library". UGC always requires an actor. Other Marketing videos use personMode: "none" only when no person is requested. No new actor is generated when lookup fails.

The catalog includes active shared looks and your personal saved looks, excluding unsaved drafts. Search uses recorded names, appearance, gender and other descriptions. The current shared catalog has no ethnicity field, so the assistant must not guess ethnicity from portraits, names, or clothing. If a request cannot be matched, it offers existing choices or asks for clarification. Shared catalog updates ship with the API; personal saved looks are read from your library.

Training presenters use list_avatars and get_avatar, then avatarId from that catalog. They are existing preset avatars, separate from Marketing actors. Avatar generation checks account access. A custom uploaded Training avatar is not supported by these tools.

API equivalents are GET /v1/marketing/actors, GET /v1/marketing/actors/{actor_id}, GET /v1/avatars, and GET /v1/avatars/{avatar_id}. Marketing accepts actor_id and person_mode; Training accepts avatar_id and infers avatar enablement. Invented IDs are rejected. Actor images are attached by the server, so users do not need to copy image URLs. Existing Marketing/Training permissions cover their respective catalogs.

The MCP repository uses only dev and main. Ongoing changes and the current Railway deployment use dev; main is retained for reviewed releases.