Claude Code

Connect Claude Code (Anthropic's terminal coding agent) to AiNecto via MCP.

---

Add the AiNecto MCP server

Use the claude mcp add command to register AiNecto at user scope:

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

Use --scope user. Without it, claude mcp add registers the server at local scope, which takes precedence over the .mcp.json that ainecto init writes — so a repository's role would never apply. With the user-scope entry, repositories you have run ainecto init in use their project entry (the role-carrying ainecto 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 AiNecto'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 ainecto init with your answer. See CLI → Set up a repository.

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

---

Try it

In any Claude Code session:

List my ERD documents in AiNecto.

Claude Code calls mcp__ainecto__list_documents with type=erd and prints the results.

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

Claude Code calls mcp__ainecto__erd_list_tables and mcp__ainecto__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 ainecto init, with one ainecto entry that carries the role:

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

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

---

Scopes & permissions

The token issued by AiNecto 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 AiNecto 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 ainecto init The role applies from a new session: exit and run claude -c in the repository, and approve the ainecto server from .mcp.json when asked. If the session still has no role, another ainecto entry is hiding it. Run claude mcp get ainecto; if it shows local scope, remove it with claude mcp remove ainecto -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.