Use ConceptViz from AI Agents (MCP & Skills)

This page is for anyone who wants an AI agent (Claude, ChatGPT, Claude Code, Codex, Cursor) to create diagrams with ConceptViz. It is not about the in-product Agent chat; that lives in the web app. Here your own assistant calls ConceptViz as a tool, either through a remote MCP server or through the REST API.

• MCP server URL: https://conceptviz.app/api/mcp/mcp
• Sign-in: OAuth (Claude.ai, ChatGPT) or an API key (cvk_...) sent as a Bearer token
• Credits: the same image credits as the rest of ConceptViz

Who can use it

API and MCP access follows the same rule as the API reference. It is included with every paid plan (monthly or yearly subscriptions and Lifetime), with remaining credits from a purchased credit pack, and with existing API customer accounts. New accounts can also spend their unexpired free signup credits through the API and MCP to try it out.

If you are not sure, check your plan and credits. Create or revoke API keys in Settings > API Keys.

30-second setup

Claude.ai and ChatGPT (OAuth)

1. In Claude, open Settings > Connectors > Add custom connector. In ChatGPT, enable developer mode and add a connector.
2. Paste https://conceptviz.app/api/mcp/mcp and choose OAuth.
3. Sign in to ConceptViz and approve access. No API key is needed.

Claude Code

claude mcp add --transport http conceptviz https://conceptviz.app/api/mcp/mcp \
  --header "Authorization: Bearer $CONCEPTVIZ_API_KEY"

Run /mcp inside Claude Code to confirm the server is connected. You can also leave out --header and sign in with OAuth from the /mcp menu.

To install ConceptViz as a plugin instead (MCP server plus a skill with usage tips):

/plugin marketplace add zane-labs/agent-skills
/plugin install conceptviz@zane-agent-skills

Codex

Add the server with the CLI:

export CONCEPTVIZ_API_KEY=cvk_your_api_key_here
codex mcp add conceptviz --url https://conceptviz.app/api/mcp/mcp \
  --bearer-token-env-var CONCEPTVIZ_API_KEY

or put this in ~/.codex/config.toml (or a trusted project's .codex/config.toml):

[mcp_servers.conceptviz]
url = "https://conceptviz.app/api/mcp/mcp"
bearer_token_env_var = "CONCEPTVIZ_API_KEY"

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project), then restart Cursor:

{
  "mcpServers": {
    "conceptviz": {
      "url": "https://conceptviz.app/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CONCEPTVIZ_API_KEY}"
      }
    }
  }
}

Skills that call the REST API

Some agent skills ship small scripts instead of using MCP. They call the REST API with your API key and work the same way: submit a prompt, then poll the task. Billing and eligibility are identical.

More clients (VS Code, Grok) are covered in the MCP server guide.

Tools

Credits and billing

Each image is billed in image credits when the task is submitted, exactly like the matching REST call.

1:1 images are always generated at 2K. If a task fails, its credits are refunded automatically. See Credit Cost for details.

How waiting works

Generation takes roughly 30 to 90 seconds. create_scientific_diagram and revise_diagram wait up to about 50 seconds. If the image is ready you get the link straight away. If not, the tool returns a task_id; call get_diagram_task with it about a minute later. Do not submit the same request again, because that would create (and charge for) a new task.

Prompts to try

Copy one of these into your agent:

1. "Use ConceptViz to draw a labeled animal cell cross-section: nucleus, mitochondria, Golgi apparatus, rough ER, ribosomes and plasma membrane. Clean textbook style, 16:9."
2. "Create a ConceptViz diagram of a series circuit with a 9 V battery, a switch, two resistors in series and an ammeter, with component labels and the current direction marked."
3. "Make a process flow diagram of the water cycle for a geography class: evaporation, condensation, precipitation, runoff and groundwater, with arrows and short labels, 4:3."

To change a result, ask the agent to revise it, for example "make the arrows thicker and add a legend".

FAQ

Do I need an API key for Claude.ai or ChatGPT? No. Those connectors use OAuth. You can disconnect any time under Settings > API (Connected apps).

I get "Not enough credits". Check your balance with get_credit_balance or see pricing. Nothing is charged when a request is rejected.

I get 403 API_ACCESS_REQUIRED. Your account does not currently qualify for API and MCP access. See Who can use it.

Can it edit an image I upload or a link I paste? No. revise_diagram only works on diagrams created with your own account.

Is it for photos or people? No. It is built for scientific and educational diagrams, not photos or portraits of people.

Is my API key safe in the config file? Prefer an environment variable (as in the Codex and Cursor examples) and never commit keys to a repository. Revoke a key any time in Settings.