Claude Code

Connect Claude Code (Anthropic's terminal coding agent) to AI-ERD via MCP.

---

Add the AI-ERD MCP server

Use the claude mcp add command to register AI-ERD at user scope:

claude mcp add --scope user --transport http ai-erd https://ai-erd.com/mcp

Use --scope user. Without it, claude mcp add registers the server at local scope, which takes precedence over the .mcp.json that ai-erd init writes — so a repository's role would never apply. With the user-scope entry, repositories you have run ai-erd init in use their project entry (the role-carrying ai-erd server), and every other folder uses this one.

Claude Code will detect the OAuth requirement and walk you through authorization the first time you make a tool call:

1. A browser window opens to AI-ERD's authorization page
2. Sign in (or use an existing session)
3. Approve the consent screen
4. Claude Code receives the token and stores it in your local session

You can verify the connection with:

claude mcp list

This user-scope connection has no role. When a session has no role, the server tells Claude Code to ask you which role this repository's sessions should have and to run ai-erd init with your answer. See CLI → Set up a repository.

npx -y ai-erd@latest init                     # you, in a terminal: asks for the role and the project
npx -y ai-erd@latest init --role <role>       # an agent, with the role you chose

---

Try it

In any Claude Code session:

List my AI-ERD ERD documents.

Claude Code calls mcp__ai-erd__list_documents with type=erd and prints the results.

Open ERD document <uuid> and show me the users table.

Claude Code calls mcp__ai-erd__erd_list_tables and mcp__ai-erd__erd_get_table, then renders the schema.

---

Configuration files

Prefer the claude mcp add --scope user command above over editing files by hand — it writes the user-scope configuration for you (see the Claude Code MCP docs for where each scope is stored).

The repository's own .mcp.json is written by ai-erd init, with one ai-erd entry that carries the role:

{
  "mcpServers": {
    "ai-erd": {
      "command": "npx",
      "args": ["-y", "@ai-erd/mcp", "--role", "development"]
    }
  }
}

Do not add a local-scope ai-erd entry in such a repository; it would hide this one.

---

Scopes & permissions

The token issued by AI-ERD scopes access to your account. Claude Code can only see and modify documents you have permission to view or edit:

• OWNER / EDITOR roles → full read + write
• VIEWER role → read-only (write tool calls return a permission error)

You can revoke the token any time from AI-ERD account settings → Connected apps.

---

Troubleshooting

Browser doesn't open during auth Copy the authorization URL from the terminal and open it manually.

"plan does not include MCP" MCP requires a paid plan. Upgrade in account settings, or see Plans.

The role does not apply after ai-erd init The role applies from a new session: exit and run claude -c in the repository, and approve the ai-erd server from .mcp.json when asked. If the session still has no role, another ai-erd entry is hiding it. Run claude mcp get ai-erd; if it shows local scope, remove it with claude mcp remove ai-erd -s local and restart.

Tool call returns 401 Token expired. Re-run any tool call and Claude Code will refresh automatically, or remove and re-add the server.