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 public service, use your current ErdForge domain with /mcp appended.

Supported surface

MCP clients send JSON-RPC over HTTP POST requests to /mcp.
ErdForge currently exposes tools, resources, prompts, and structured tool responses.
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.
The public connection uses personal tokens today. Clients that require OAuth discovery should register the endpoint manually with a personal token.
Open ErdForge web sessions refresh after MCP writes through a separate app event channel.

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. Pass workspaceName to create a new workspace and save the first ERD in one request.

erdforge_delete_diagram

Delete a workspace ERD and notify open web clients.

Provided resources

erdforge://workspaces

Read the list of workspaces available to the current token.

erdforge://workspace/{workspaceId}/diagrams

Read diagram summaries for one workspace.

erdforge://workspace/{workspaceId}/diagram/{diagramId}

Read the full JSON context for one ERD.

Provided prompts

erdforge_create_erd_from_requirements

Start an ERD draft from product requirements or table notes.

erdforge_review_diagram

Review an existing ERD for keys, relationships, missing tables, and normalization risks.

erdforge_extend_diagram

Extend an existing ERD with concrete changes for a new feature.

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

Save directly into a new workspace

With a full-scope token, pass workspaceName to erdforge_upsert_diagram to create a workspace and save the first ERD in one call.

{
  "name": "erdforge_upsert_diagram",
  "arguments": {
    "workspaceName": "Billing DB structure",
    "diagramId": "billing_schema",
    "name": "Billing PostgreSQL Schema",
    "dialect": "PostgreSQL",
    "tables": [
      { "name": "accounts", "columns": [{ "name": "id", "type": "uuid", "primaryKey": true }] }
    ],
    "relations": []
  }
}

Connection check

After registering the client, call these JSON-RPC methods with the same endpoint and headers. Check token scope and available workspaces before running write tools.

1. initialize
2. tools/list
3. resources/templates/list
4. prompts/list
5. resources/list

POST <your-domain>/mcp
Accept: application/json, text/event-stream
Authorization: Bearer erdforge_mcp_...
MCP-Protocol-Version: 2025-11-25

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.
GET or DELETE requests return 405. The ErdForge MCP endpoint currently uses request-response HTTP POST only.
Tool responses include readable text plus structuredContent that clients can validate.
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.