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 exposes 35 tools — 6 read-only and 29 mutation tools — giving full parity with the in-app AI assistant.

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>"

Available MCP Tools

The MCP API provides 35 tools total:

Read tools (6):

  • get_metamodel — understand the model's schema
  • search_nodes — find nodes by type, name, or properties
  • get_node_details — get full details for specific nodes
  • get_relationships — find connections between nodes
  • get_statistics — model stats and counts
  • find_similar_nodes — detect potential duplicates

M1 node mutations (4):

  • create_nodes — create new node instances
  • update_nodes — update node properties and labels
  • delete_nodes — remove nodes (cascades diagram placements)
  • merge_nodes — merge duplicate nodes

M1 relationship mutations (5):

  • create_relationships — create relationships between nodes
  • update_relationships — update relationship properties and labels
  • delete_relationships — remove relationships
  • update_relationship_label — set a relationship's display label
  • set_relationship_property — set a single property on a relationship

M2 metamodel mutations (8):

  • add_node_type — add a new node type to the metamodel
  • update_node_type — rename or update a node type
  • remove_node_type — remove a node type (cascades instances)
  • add_relationship_type — add a new relationship type
  • update_relationship_type — rename or update a relationship type
  • remove_relationship_type — remove a relationship type (cascades instances)
  • add_allowed_connection — add a connection rule between types
  • remove_allowed_connection — remove a connection rule

Organization (4):

  • create_folder — create a folder in the tree
  • move_to_folder — move nodes into a folder
  • create_sticky_note — add a sticky note
  • update_sticky_note — edit a sticky note's text

Diagram mutations (8):

  • create_diagram — create a new diagram
  • rename_diagram — rename a diagram
  • delete_diagram — delete a diagram
  • add_node_to_diagram — place a node on a diagram
  • remove_node_from_diagram — remove a node placement from a diagram
  • add_relationship_to_diagram — show a relationship on a diagram
  • remove_relationship_from_diagram — hide a relationship from a diagram
  • set_node_position — set a node's x/y position on a diagram

Filter mutations (2):

  • create_filter — create a saved node filter
  • delete_filter — delete a saved filter

Tips

  • Start with get_metamodel to understand the model's structure
  • All mutations are applied in real-time — browser users see changes immediately
  • 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.