theo

mcp

MCP Server & API Keys

Connect OpenCharts to external AI tools using the Model Context Protocol. Build full websites & apps, flowcharts, notes, and presentations 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 32 tools + 3 resources, verification steps, and troubleshooting — everything an agent needs to install it in one paste.

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

Your IDEWarp · Claude · Cursor · VS Code

MCP ProtocolStreamable HTTP + Bearer auth

OpenCharts32 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.

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

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

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

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

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

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) 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 and extract_flowchart 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?