MCP connection guide

Let AI agents read and write ERDs directly

ErdForge exposes an MCP endpoint for AI agents that need workspace context, ERD JSON, and safe write access. Create a personal token from the dashboard, register it in your MCP client, and your agent can inspect or update diagrams.

Create an MCP ERD workspace Start with Google

Endpoint/mcp

1. Create a personal token

After signing in, use the dashboard MCP token panel to choose workspace scope and an expiration period for a personal token.

Authorization: Bearer erdforge_mcp_...

2. Register the MCP client

Add the endpoint and Bearer token to your MCP client configuration.

{
  "url": "<your-domain>/mcp",
  "transport": "streamable-http",
  "headers": {
    "Accept": "application/json, text/event-stream",
    "Authorization": "Bearer erdforge_mcp_...",
    "MCP-Protocol-Version": "2025-11-25"
  }
}

For the local production container, use http://localhost:4173/mcp.

Supported surface

MCP clients send requests to /mcp.
Open web sessions receive MCP upsert/delete changes through SSE and refresh the current ERD.
Personal Bearer tokens follow the issuing user's permissions and selected workspace scope.
Full-scope tokens can create new workspaces with workspaceName; scoped tokens are limited to selected workspaces.

Provided tools

erdforge_list_workspaces

List accessible workspaces and the current selection.

erdforge_create_workspace

Create a new ERD workspace and prepare it for saving.

erdforge_list_diagrams

List ERDs by workspace with table and relationship counts.

erdforge_get_diagram

Read an existing ERD JSON document as editing context.

erdforge_upsert_diagram

Create or update an ERD with tables, columns, and relationships.

erdforge_delete_diagram

Delete a workspace ERD and notify open web clients.

ERD creation example

ErdForge can normalize simple table specifications into canvas-ready IDs, coordinates, and column IDs.

{
  "name": "Order Core",
  "dialect": "PostgreSQL",
  "tables": [
    { "name": "users", "columns": [{ "name": "id", "type": "uuid", "primaryKey": true }] },
    { "name": "orders", "columns": [{ "name": "user_id", "type": "uuid", "foreignKey": true }] }
  ],
  "relations": [
    {
      "sourceTable": "orders",
      "sourceColumn": "user_id",
      "targetTable": "users",
      "targetColumn": "id"
    }
  ]
}

Fallback for company accounts that cannot use MCP

If a company security policy or harness setting blocks MCP registration in Claude Code, use a human-reviewed JSON import flow that stays inside the approved policy.

Ask the AI agent to output only ErdForge JSON with tables, columns, and relationships.
Open the workspace in ErdForge and paste the result into Import JSON.
Review red type warnings, relationship direction, PK/FK, and naming in the web UI before saving.
If automated writes are required, use an approved MCP client or automation account with narrow token scope.

Operational notes

Tokens only act with the issuing user's permissions.
Expired or revoked tokens are rejected immediately.
Use narrow workspace scope for automation that should not touch every ERD.
When MCP is blocked by policy, use the web UI's Import JSON flow as the default fallback.
MCP writes and approved automation writes are recorded in audit history with the user, token, workspace, and ERD context.