Using Metapad via MCP (Claude Desktop / Claude Code)

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

Pro plan or higher
Claude Desktop or Claude Code installed
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

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

Connecting Claude Code

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

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