Using Metapad via MCP (Claude Desktop / Claude Code)

Advanced

How to connect external AI tools like Claude Desktop or Claude Code to your Metapad models using the MCP protocol.

Metapad implements the Model Context Protocol (MCP), allowing external AI tools like Claude Desktop and Claude Code to read and modify your models.

What is MCP?

MCP is a standard protocol that lets AI assistants interact with external data sources. Metapad's MCP API gives external tools the same reach as the in-app AI assistant — the whole modelling surface, from reading the metamodel to running a simulation.

Prerequisites

  1. Pro plan or higher
  2. Claude Desktop or Claude Code installed
  3. Either an API token (see "API Tokens and External Access") or an OAuth login (see "Connecting MCP via OAuth")

Authentication Options

Metapad supports two ways to authenticate MCP connections:

  • OAuth (recommended for interactive use): Just log in with your Metapad credentials — no token needed. See "Connecting MCP via OAuth" for details.
  • API tokens: Create an mpt_... token for scripts, CI/CD, or automation. See "API Tokens and External Access".

Connecting Claude Desktop

  1. Open Claude Desktop settings
  2. Find the MCP Servers configuration
  3. Add a new MCP server with:
    • Type: HTTP
    • URL: Your Metapad MCP endpoint
    • Authentication: OAuth (automatic) or Bearer token (mpt_...)
  4. Save and restart Claude Desktop
  5. If using OAuth, a login window will open — sign in with your Metapad credentials
  6. Claude can now query and modify your model

Connecting Claude Code

  1. Configure the MCP server in your project's .claude/settings.json or via CLI.
  2. Use the same endpoint URL and API token
  3. Claude Code can now interact with your model during coding sessions

Command for the CLI:

claude mcp add --transport http <name> \
  https://app.metapad.ai/mcp/<model_uuid> \
  --header "Authorization: Bearer <mpt_token>"

What Claude can do with your model

Metapad exposes close to a hundred tools over MCP. Rather than list them here — the list keeps growing — the short version is that anything you can do in the app, you can ask Claude to do:

  • Explore — read the metamodel, search and filter nodes, follow relationships, list the tags in use, spot likely duplicates, get model statistics
  • Model — create, update, merge and delete nodes, relationships and the types behind them; set which types may connect
  • Edit prose in place — change one paragraph of a description or a published document without rewriting the whole text
  • Organise — folders, saved filters, tags, navigation trees
  • Draw — create diagrams and place elements and relationships on them
  • Publish — author document renderings and publications, and render a page or a whole site back as text
  • Simulate — build twins, scenarios and agents, set parameters and time series, and run a simulation to get the computed results back
  • Translate — list every translatable string in the model and write translations back
  • Assets — upload files, list them, and read their contents

The full, current tool list with parameters and examples is in the MCP API Reference. You never need to name a tool by hand — Claude reads the list from the server itself.

Tips

  • Start by asking Claude to look at the metamodel — it grounds everything that follows
  • Changes apply immediately, and anyone with the model open sees them appear
  • When Claude creates something, it tells you the ID it got — including the auto ID, like REQ-42, so you can refer to it straight away
  • Destructive changes save a version first, so you can roll back from version history
  • MCP access respects the same model data as the web UI
  • OAuth connections show your name to collaborators; API tokens show "mcp-api"
  • Everything you can do via the in-app AI assistant is also available through MCP
Next →

Using the AI Assistant

This content was written collaboratively with AI.