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.

Endpoint/mcp

1. Create a personal token

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

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

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.