theo

mcp

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.

Create an API key first →

Includes the endpoint, every IDE's config, all 87 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.

Add to Cursor

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 87 tools and 5resources, letting you build full websites & apps, presentations, flowcharts, notes, images, and video entirely from your development environment.

Your IDEWarp · Claude · Cursor · VS Code

MCP ProtocolStreamable HTTP + Bearer auth

OpenCharts87 tools · 5 resources

Build full websites & apps with Code Canvas — generate, then open the live project.

Create flowcharts, whiteboards, notes, and presentations from any AI client.

Generate images and short videos on demand — embed the returned URLs instead of placeholders.

Ask Theo AI or extract flowcharts from uploaded documents (PDFs, images, PPTXs).

Manage projects — list, update, delete — all via tool calls.

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.

API key securityAPI keys are hashed before storage — OpenCharts never stores the raw key. The full key is shown only once at creation. If lost, revoke and create a new one.

MCP endpoint

Server URL

https://www.opencharts.com/api/mcp

Transport: Streamable HTTP (POST). Authentication: Bearer token (API key or JWT).

Platform setup

Available tools (87)

Projects (8)

list_projectsList your projects with pagination and filters

get_projectGet full project data by ID

create_flowchartCreate a flowchart project with nodes and edges

create_whiteboardCreate a whiteboard with native shapes and elements

create_notesCreate a notes project from Markdown

create_presentationCreate a slide deck from an outline

update_projectUpdate metadata or content (notes, flowchart, whiteboard, or presentation)

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 poll

get_code_canvas_statusPoll a Code Canvas build; returns the project + open URL when ready

get_code_projectRead an existing code project — file list, or selected files' full content

update_code_projectEdit an existing code project — upsert/delete files; preview updates live

AI (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 (13)

build_agentBuild a Theo Agent from a description — runs in the background, notifies you when ready

get_agent_build_statusOptional poll for a build_agent job; returns the agent + open URL when done

create_agentCreate a Theo Agent deterministically from structured steps + trigger

update_agentPatch an agent's name, description, or step list

configure_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 firing

delete_agentSoft-delete an agent (30-day recovery)

list_agentsList your Theo Agents with status + step counts

get_agentGet an agent's full definition (trigger + ordered steps)

run_agentDispatch an agent now — runs in the background, notifies you on completion

list_agent_runsList an agent's recent execution runs

get_agent_run_statusGet a single run's status + per-node progress

Theo Sheets (12)

list_sheetsList your Theo Sheets spreadsheet projects

inspect_sheetInspect a sheet — per-tab dimensions, header row, sampled cells + formulas, layout

get_sheetExtract a worksheet as structured rows (headers + data rows)

read_sheet_rangeRead an exact A1 range's values (+ optional formulas) as a grid + CSV

create_sheetCreate a live spreadsheet (Excel-grade grid + formulas) from headers and rows

update_sheetEdit a sheet by applying structured spreadsheet edit ops — saved as a rollback-able commit

apply_sheet_opsApply structured spreadsheet edit ops — or propose a merge-gated change

edit_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 proposal

resolve_sheet_proposalMerge or reject a pending change proposal

rollback_sheetRoll the live sheet back to a prior commit (reversible)

Boards (10)

create_boardCreate a Kanban + calendar project board

list_boardsList your project boards

get_boardGet a board's lists (columns) and cards

update_boardUpdate a board's name, description, or list columns

delete_boardSoft-delete a board (recoverable)

duplicate_boardDuplicate a board with its lists, rules, and cards

add_board_cardAdd a card (post/task/idea/event) to a board

list_board_cardsList a board's cards, optionally by schedule range

update_board_cardEdit a card — move list, reschedule, change status/color

delete_board_cardSoft-delete a card from a board

Theo Symphony (2)

create_songGenerate a song with Theo Symphony — returns a job to poll

get_song_statusPoll a song job; returns audio + cover-art versions when complete

Theo Media (4)

generate_imageGenerate an image from a prompt — returns a public URL to embed or save (use instead of placeholders)

generate_videoGenerate a video clip from a prompt — pick a Theo Reel tier (Fast → Cinema Ultra); returns a job to poll

get_video_statusPoll a video job; returns the tier, quality and finished clip URL

get_media_capabilitiesList the video tiers and image engines this workspace can generate, with lengths, quality menus and relative cost

Theo Personas (7)

list_personasList your video personas with their publish status

get_personaRead one persona — character, greeting, knowledge, face, and its share links

list_persona_facesList the faces a persona can wear — a persona needs one before it can be published

create_personaCreate a video persona: give it a name, a character, a greeting and a face

update_personaEdit a persona — only the fields you pass change

publish_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 browser

Notes (3)

get_note_contentExtract a note's content as Markdown

append_to_noteAppend Markdown content to an existing note

clip_to_noteSave web content (URL + HTML) as a clip inside a note

Templates (2)

list_templatesBrowse the template gallery

use_templateCreate a new project from a template

Theo Designs (6)

list_page_projectsList your page designs (posters, flyers, social ads, invitations)

get_page_docRead a design's pages, elements and brand

list_ad_templatesBrowse social-ad templates laid out on Instagram's own safe zones

create_page_projectCreate a design from an ad template or a blank canvas

apply_page_opsEdit a design with the same op engine the in-app assistant uses

generate_ad_setGenerate one design per ad placement, adapted from a single master

Note Canvas (12)

list_canvasesList your Note Canvas boards — infinite canvases of connected cards

get_canvasRead a board as a graph: cards, their text, and the connections between them

get_canvas_contextGather the cards that feed one card, by walking its connections upstream

search_canvasesFind a board by name, or by text written on one of its cards

list_canvas_backlinksFind which boards reference a given note

read_canvas_noteRead one note card in full as Markdown — the graph read only carries an excerpt

export_canvasExport a board as JSON Canvas (.canvas) — the open format Obsidian reads

create_canvasCreate a board, optionally seeded with cards and the connections between them

apply_canvas_opsEdit a board — add, connect, group, recolour and move cards by relative placement

write_canvas_noteAppend to (or rewrite) the note behind a card — the board's copy catches up on its own

relayout_canvasTidy a whole board: lay every card out along its connections

import_canvasCreate a board from a JSON Canvas (.canvas) file

Account (2)

whoamiGet the authenticated user's profile information

get_creditsCheck remaining AI credit balance

Video 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 · Fast

0.4× the cost of Maxfixed ~8s1080p1 ref

Quickest and cheapest. A fixed ~8s 1080p clip — good for a background loop, a placeholder, or iterating on an idea.

maxTheo Reel · Max

1× the cost of Maxfixed ~8s1080p1 ref

The default. The same fixed ~8s 1080p clip as Fast at higher fidelity — the right choice when you have no specific requirement.

cinemaTheo Reel · CinemaPremium

5.3× the cost of Maxup to 15sup to 4k9 refs

Premium 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 UltraPremium

6.7× the cost of Maxup to 30sup to 720p30 refs

Longest single take — up to 30s of continuous action, and up to 30 reference images. Tops out at 720p: it trades the top of the quality menu for length and coherence.

Ask before you spendA premium render costs several times a standard one, so a placeholder loop does not need one. Call `get_media_capabilities` to see which tiers YOUR workspace can actually serve, what each costs, and whether a length, quality or frame shape is reachable. It is read-only and costs nothing. Ask for something a tier cannot do and it steps DOWN to that tier's ceiling rather than failing: the response reports every adjustment in `notes`, so nothing is silently ignored.

Resources (5)

MCP resources provide read-only context that AI clients can retrieve without calling a tool.

projectsPaginated list of your recent projects

projectFull data for a single project by ID

templatesBrowsable template catalog

canvasesYour Note Canvas boards, most recently worked on first

canvasOne board as a graph of cards and the connections between them

API key management

Create

Copy

Use

Revoke

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 GitHub

AI Chat

Conversational AI that creates flowcharts, whiteboards, notes, and presentations from natural language.

Integrations, Webhooks, and Zapier

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.

Was this article helpful?