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 67 tools + 3 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 /theo-agents/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 67 tools and 3resources, 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

OpenCharts67 tools · 3 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 (67)

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 (3)

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

generate_videoGenerate a short video clip from a prompt — returns a job to poll

get_video_statusPoll a video job; returns the finished clip URL when complete

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

Account (2)

whoamiGet the authenticated user's profile information

get_creditsCheck remaining AI credit balance

Resources (3)

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

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?