MCP Server & API Keys
Connect OpenCharts to external AI tools using the Model Context Protocol. Build full websites & apps, flowcharts, notes, presentations, images, and video from any MCP-compatible client.
Fastest setup — let your AI install it
Copy this prompt and paste it into Claude Code, Cursor, Warp, Windsurf, GitHub Copilot, Codex, Amp, or OpenCode. Your AI assistant detects your IDE, writes the correct MCP config, reloads the server, and verifies the connection — you only provide your API key.
Includes the endpoint, every IDE's config, all 129 tools + 5 resources, verification steps, and troubleshooting — everything an agent needs to install it in one paste.
One-click install
Prefer a shortcut? Add OpenCharts to Cursor in one click, or paste a single command into your terminal. You'll still add your API key once — create one at /developers/mcp.
What is MCP?
The Model Context Protocol (MCP) is an open standard that lets AI tools interact with external services through a unified interface. OpenCharts provides a public MCP server that exposes 129 tools and 5 resources, letting you build full websites & apps, presentations, flowcharts, notes, images, and video entirely from your development environment.
Quick start
Go to the Skill Store → MCP Server tab, or Settings → Integrations → MCP & API Keys.
Click "Create Key", give it a name (e.g. "Warp"), and copy the generated key immediately.
Expand your platform below and copy the config snippet.
Paste the config into your tool's MCP settings file, replacing {{YOUR_API_KEY}} with your key.
Test the connection — try calling the `whoami` tool to verify authentication.
MCP endpoint
Server URL
https://www.opencharts.com/api/mcpTransport: Streamable HTTP (POST). Authentication: Bearer token (API key or JWT).
Platform setup
Available tools (129)
Projects (9)
list_projectsList your projects with pagination and filtersget_projectGet full project data by IDcreate_flowchartCreate a flowchart project with nodes and edgescreate_whiteboardCreate a whiteboard with native shapes and elementscreate_notesCreate a notes project from Markdowncreate_presentationCreate a slide deck from a brief or outline — slides generate in the background; poll get_presentation_statusget_presentation_statusPoll a presentation generation job; returns per-slide progress + the deck URL when readyupdate_projectUpdate metadata or content (notes, flowchart, whiteboard, or presentation — deck content rebuilds in the background)delete_projectSoft-delete a project (30-day recovery)Code Canvas (4)
generate_code_canvasBuild a full website or app (HTML/React) from a description — returns a job to pollget_code_canvas_statusPoll a Code Canvas build; returns the project + open URL when readyget_code_projectRead an existing code project — file list, or selected files' full contentupdate_code_projectEdit an existing code project — upsert/delete files; preview updates liveAI (2)
ask_theoSend a single-turn AI message (fast or think mode)extract_flowchartExtract a flowchart from an uploaded document (PDF, image, PPTX)Theo Agents (15)
build_agentBuild a Theo Agent from a description — runs in the background, notifies you when readyget_agent_build_statusOptional poll for a build_agent job; returns the agent + open URL when donecreate_agentCreate a Theo Agent deterministically from structured steps + triggerupdate_agentPatch an agent's name, description, or step listconfigure_agent_triggerSet an agent's trigger (manual, schedule, webhook, event, telegram)activate_agentActivate an agent (seeds the first scheduled run)deactivate_agentDeactivate an agent so triggers stop firingdelete_agentSoft-delete an agent (30-day recovery)list_agentsList your Theo Agents with status + step countsget_agentGet an agent's full definition (trigger + ordered steps)run_agentDispatch an agent now — runs in the background, notifies you on completionsend_agent_messageTalk to a goal-driven agent on a conversation thread — returns a runId to poll for its replyget_agent_run_resultGet what a run produced — the agent's reply, artifacts, or the approval it is waiting onlist_agent_runsList an agent's recent execution runsget_agent_run_statusGet a single run's status + per-node progressTheo Sheets (12)
list_sheetsList your Theo Sheets spreadsheet projectsinspect_sheetInspect a sheet — per-tab dimensions, header row, sampled cells + formulas, layoutget_sheetExtract a worksheet as structured rows (headers + data rows)read_sheet_rangeRead an exact A1 range's values (+ optional formulas) as a grid + CSVcreate_sheetCreate a live spreadsheet (Excel-grade grid + formulas) from headers and rowsupdate_sheetEdit a sheet by applying structured spreadsheet edit ops — saved as a rollback-able commitapply_sheet_opsApply structured spreadsheet edit ops — or propose a merge-gated changeedit_sheetEdit a sheet with a natural-language instruction (Theo plans + applies ops)list_sheet_commitsList a sheet's git-style change commits (applied / proposed / merged)diff_sheet_commitShow the cell-level diff for a commit or proposalresolve_sheet_proposalMerge or reject a pending change proposalrollback_sheetRoll the live sheet back to a prior commit (reversible)Boards (10)
create_boardCreate a Kanban + calendar project boardlist_boardsList your project boardsget_boardGet a board's lists (columns) and cardsupdate_boardUpdate a board's name, description, or list columnsdelete_boardSoft-delete a board (recoverable)duplicate_boardDuplicate a board with its lists, rules, and cardsadd_board_cardAdd a card (post/task/idea/event) to a boardlist_board_cardsList a board's cards, optionally by schedule rangeupdate_board_cardEdit a card — move list, reschedule, change status/colordelete_board_cardSoft-delete a card from a boardTheo Symphony (2)
create_songGenerate a song with Theo Symphony — returns a job to pollget_song_statusPoll a song job; returns audio + cover-art versions when completeTheo Media (4)
generate_imageGenerate an image from a prompt — pick an engine (Theo Ultra is the default on paid plans; Grok + Theo optional) and get a public URL to embed or savegenerate_videoGenerate a video clip from a prompt — pick a Theo Reel tier (Fast → Cinema Ultra); returns a job to pollget_video_statusPoll a video job; returns the tier, quality and finished clip URLget_media_capabilitiesList the video tiers and image engines this workspace can generate, with lengths, quality menus and relative costDirector Mode (6)
get_director_optionsList what Director Mode renders here — tiers with their lengths, qualities, frames and prices, your saved characters, the limits, and how to write a takecreate_director_takeStart a film production, or roll the next take on one — change a shot, continue it, start a new scene, cast saved characters, and bring reference imagesget_director_productionRead a production — scenes, takes with clip links, why a take failed and what to try, and its Final Cuts — or list your recent productionsreview_director_takeHave Theo watch a finished take and report what it shows, what looks wrong, and how it compares with its noteupdate_director_productionOrganize a production's scenes — add, rename or reorder a scene, or pick the take a scene gives the filmcreate_director_final_cutAssemble a production's scenes into one film in the background, with the takes' own soundTheo Kata (3)
create_kata_videoRe-perform a clip's exact moves with a new cast (Recast) or a new cast in a new world (Motion transfer) — returns a take to pollget_kata_video_statusPoll a Theo Kata take; returns the finished clip URL, or why it failed and what to try nextget_kata_optionsList Theo Kata's modes, reference lanes, style presets, clip limits, prices and your saved charactersDirector Editor (4)
create_director_editStart an edit in Director's cutting room from footage you already own — productions' takes and cuts, or videos already in your account — laid on the timeline and prepared (proxy + transcript) in the backgroundget_director_editRead an edit — its sources and their preparation status, the timeline, its exports with watch links and Theo's latest proposals — or list your recent editsplan_director_editAsk Theo to propose a cut from the transcripts (rough cut, cut to length, highlights, chapters, score, narration or free direction) and optionally apply it as one saveexport_director_editRender an edit's cut in the background at a chosen frame, resolution and container, optionally with Theo Enhance — the file lands on the edit's Export shelfTheo Personas (21)
list_personasList your video personas with their publish statusget_personaRead one persona — character, greeting, knowledge, face, and its share linkslist_persona_facesList the faces a persona can wear — the stock library plus the likenesses you trainedget_persona_faceCheck a likeness you are training — status, face id, and its default voiceget_persona_voiceCheck a voice you are cloning — status and the voice id to pin on a personacreate_personaCreate a video persona: give it a name, a character, a greeting, a face and its capabilities (Pro + Teams)update_personaEdit a persona — only the fields you pass change; `capabilities` sets its tool allow-listpublish_personaPublish a persona so it can take live video calls (safe to re-run after edits)deploy_personaGive a published persona a share link anyone can call from a browsercreate_persona_faceClone a likeness from a public training video or headshot URL — trains in the backgroundcreate_persona_voiceClone a speaking voice from a public audio sample URL — ready in minutesawait_persona_requestAgent Link: wait for the next task a live persona hands off to you (run in a loop to be its brain)report_persona_progressAgent Link: post what you are doing on a claimed task so the owner's dashboard shows it livereply_to_personaAgent Link: send your answer back so the persona speaks it on the callsync_agent_previewsPaired desktop bridge only: renew owner-approved website previews and report readinessagent_control_tokenPaired desktop bridge only: a scoped token for relaying a controlled conversation to the owner's browserlist_persona_requestsAgent Link: recent hand-offs from your personas — what was asked, what came back, who is listeningconnect_agent_linkAgent Link: connect your own computer as your personas' brain — returns one command to run, no key to pasteget_agent_link_statusAgent Link: is your computer connected right now, and which personas hand work to ittest_agent_linkAgent Link: send one real test hand-off to your connected agent and report its answerfetch_agent_contextAgent Link bridge only: fetch the bytes of files a browser staged for a turn (re-verified by size and hash)Notes (3)
get_note_contentExtract a note's content as Markdownappend_to_noteAppend Markdown content to an existing noteclip_to_noteSave web content (URL + HTML) as a clip inside a noteTemplates (2)
list_templatesBrowse the template galleryuse_templateCreate a new project from a templateTheo Designs (6)
list_page_projectsList your page designs (posters, flyers, social ads, invitations)get_page_docRead a design's pages, elements and brandlist_ad_templatesBrowse social-ad templates laid out on Instagram's own safe zonescreate_page_projectCreate a design from an ad template or a blank canvasapply_page_opsEdit a design with the same op engine the in-app assistant usesgenerate_ad_setGenerate one design per ad placement, adapted from a single masterNote Canvas (12)
list_canvasesList your Note Canvas boards — infinite canvases of connected cardsget_canvasRead a board as a graph: cards, their text, and the connections between themget_canvas_contextGather the cards that feed one card, by walking its connections upstreamsearch_canvasesFind a board by name, or by text written on one of its cardslist_canvas_backlinksFind which boards reference a given noteread_canvas_noteRead one note card in full as Markdown — the graph read only carries an excerptexport_canvasExport a board as JSON Canvas (.canvas) — the open format Obsidian readscreate_canvasCreate a board, optionally seeded with cards and the connections between themapply_canvas_opsEdit a board — add, connect, group, recolour and move cards by relative placementwrite_canvas_noteAppend to (or rewrite) the note behind a card — the board's copy catches up on its ownrelayout_canvasTidy a whole board: lay every card out along its connectionsimport_canvasCreate a board from a JSON Canvas (.canvas) fileEnterprise Wiki (4)
list_wiki_spacesList your wiki spaces — the company knowledge map with ids, counts, and AI digestssearch_wikiSearch the company knowledge base (policies, SOPs, brand docs, uploads) with chainable hit idsread_wiki_articleRead one wiki article or file in full — search snippets only carry an excerptsave_to_wikiSave new knowledge as a draft wiki article, governed by the team's review workflowDrive (8)
list_drive_filesBrowse your Drive — files, the folder tree and the storage meter (needs a key with Drive access)search_drive_filesSearch your Drive by name, tag, description, shared files, and the text inside your documentsread_drive_fileRead one Drive file as text — plain text and code as-is, PDFs and Office documents parsedget_drive_fileGet a file's metadata plus a time-limited download URL for its raw bytescreate_drive_folderCreate a Drive folder, optionally nestedupdate_drive_fileRename, move, star, tag or describe one Drive fileorganize_drive_filesBulk move, star, unstar, trash (30-day restore) or restore many Drive filessave_to_driveSave a new file into Drive — text, or any format as base64 up to 4 MBAccount (2)
whoamiGet the authenticated user's profile informationget_creditsCheck remaining AI credits, the plan, and which plan-gated features it includesList only the tools you need
A connection lists every tool by default. Most agents use one part of OpenCharts, and some clients cap how many tools a server may list. Name the tool groups you want, in the server URL or in a header, and that connection lists only those, plus the two Account tools.
In the server URL
https://www.opencharts.com/api/mcp?toolsets=videoOr as a header
X-OpenCharts-Toolsets: media,sheets`video` is a preset for every group that makes or cuts video: Theo Media, Director Mode, Theo Kata, Director Editor. Every other name is one group, and several can be combined with commas.
projectsProjectscode_canvasCode CanvasaiAIagentsTheo AgentssheetsTheo SheetsboardsBoardssymphonyTheo SymphonymediaTheo MediadirectorDirector ModekataTheo Katadirector_editorDirector EditorpersonasTheo PersonasnotesNotestemplatesTemplatesdesignsTheo Designsnote_canvasNote CanvaswikiEnterprise WikidriveDriveaccountAccountVideo tiers
`generate_video` renders on one of four tiers. Pass the one you want as `model_tier`, or let your agent read the ladder from the tool description and ask you which. Cost is quoted relative to a Max render.
fastTheo Reel · FastQuickest and cheapest. A fixed ~8s 1080p clip — good for a background loop, a placeholder, or iterating on an idea.
maxTheo Reel · MaxThe default. The same fixed ~8s 1080p clip as Fast at higher fidelity — the right choice when you have no specific requirement.
cinemaTheo Reel · CinemaPremiumPremium quality. Up to 15s in one continuous take, up to 4k, six frame shapes, and up to 9 reference images. Pick this when the clip is the hero of the page.
cinema-ultraTheo Reel · Cinema UltraPremiumLongest single take — up to 30s of continuous action, and up to 30 reference images. Tops out at 1080p: it trades the top of the quality menu for length and coherence.
Direct a film
`generate_video` makes one standalone clip. A film is different: several shots that belong together, takes you revise, characters that come back. For that, your agent uses the Director Mode tools. Its takes are Director Mode's own, at the same price, and they land in the same studio, so you can open any production and keep directing.
Call `get_director_options` first. It is free, and it lists the tiers your workspace renders with their lengths, qualities, frames and prices, what your plan includes, your saved characters, and how to write a take for each tier.
Start the film with `create_director_take` and keep the production id it returns. Every later take, scene and cut passes that id.
Wait for the take with `get_director_production`, then have Theo watch it with `review_director_take` before your agent shows it to you.
Give notes the way you would in the studio. A new take can change the last one, continue it, start the shot over, or open a new scene. Cast a saved character to keep a face the same from scene to scene.
Pick each scene's keeper with `update_director_production`, then assemble the film with `create_director_final_cut`.
Renders run in the background
A clip, a Director Mode take, a Theo Kata take, an Editor export and a Final Cut all render in the background. The tool that starts one answers at once with a job to check, and every one of these tools keeps the same three promises.
Start it once
Pass `idempotency_key`, a unique string for this render, when you start one. If the call times out or the connection drops, repeat it with the same key and the same arguments. You get the original render back, and nothing is started or charged twice.
Wait in one call
Pass `wait_seconds` (up to 25) to the status tool. The call is held until the render settles, so your agent does not have to ask again every few seconds.
One answer everywhere
Every status reply carries `state` (queued, working, done or failed), `done` (stop asking) and `next` (the one call to make now).
Resources (5)
MCP resources provide read-only context that AI clients can retrieve without calling a tool.
projectsPaginated list of your recent projectsprojectFull data for a single project by IDtemplatesBrowsable template catalogcanvasesYour Note Canvas boards, most recently worked on firstcanvasOne board as a graph of cards and the connections between themAPI key management
Create: Settings → Integrations → MCP & API Keys → Create Key. Each key has a name, scopes (read, write, ai), and a prefix shown for identification.
Revoke: Click the trash icon next to any active key. Revoked keys immediately stop working. You can create up to 10 active keys.
Scopes: By default, keys have full access (read + write + ai). Scope enforcement allows restricting keys to read-only access.
Rate limits
The MCP endpoint allows 120 requests per minute per user. AI tools that consume credits (ask_theo, extract_flowchart, generate_image, generate_video, create_song) are additionally gated by your plan's credit balance.
Troubleshooting
307 redirect / "no authorization support detected"
Make sure the URL is https://www.opencharts.com/api/mcp (with www). Using opencharts.com without www causes a redirect that strips your Authorization header, resulting in auth failure.
401 Unauthorized
Your API key is missing, expired, or revoked. Generate a new key in Settings → Integrations → MCP & API Keys.
429 Too Many Requests
You've exceeded the 120 requests/minute rate limit. Wait a moment and retry. AI-heavy tools also consume credits.
Tools not appearing in my AI client
Ensure the MCP server URL is exactly https://www.opencharts.com/api/mcp (with www). Using opencharts.com without www causes a redirect that strips your API key. The Authorization header must use the "Bearer" prefix. Restart your AI client after changing config.
Some tools are listed in the docs but missing in my client (e.g. list_agents, build_agent)
Your MCP client cached an older tool list. Fully restart the host tool, or toggle the OpenCharts MCP server off and back on, so it re-fetches the tool list. Also confirm your key carries the read, write, and ai scopes — default keys include all three.
JWT expired mid-session
JWTs from Appwrite sessions expire after 15 minutes. For long-running integrations, use a persistent API key instead of a JWT.
AI credits consumed unexpectedly
Tools like ask_theo, extract_flowchart, generate_image, generate_video, and create_song consume AI credits. Use the get_credits tool to check your balance before expensive operations.
Documentation on GitHub
The full MCP server documentation — capabilities, tools, resources, and compatible clients — is also available on GitHub.
View on GitHubRelated Articles
AI Chat
Conversational AI that creates flowcharts, whiteboards, notes, and presentations from natural language.
Integrations, Webhooks, and Zapier
Connect your apps from chat or the Connections page, set up outbound webhooks, connect Zapier automations, and use practical recipe patterns.
Skills & Automation
Install skills to extend Theo, automate tasks with hooks and workflows, and manage credit guards.