AiNecto

ainecto — AiNecto CLI and MCP connector

Published as ainecto, @ainecto/mcp and @ainecto/cli — the same code. Command: ainecto.

Once per machine: npx -y ainecto@latest setup — signs you in through the browser (once), checks the connection, and connects Claude Code, Cursor, and Codex to the AiNecto server address (https://ainecto.com/mcp). Each agent then signs in to AiNecto by itself the first time it connects.

Every AI session sees the same AiNecto tools. What a tool may change is decided by your AiNecto permissions on the workspace, project, or document it touches — the server refuses the rest. There are no session roles (Design / Development / Test / Validation were removed in 0.8.0).

For AI agents

Run `npx -y ainecto@latest setup` (use a long command timeout — at least 6 minutes: sign-in waits up to 5 minutes for the user). Then run `npx -y ainecto@latest doctor` and do what it says.

• setup registers the server address, so each agent signs in on its own the first time: Claude Code — run /mcp in a session and sign in to ainecto; Cursor — sign in when ainecto asks in its MCP settings; Codex — signs in while setup connects it (a browser tab opens and the sign-in link is printed to stderr; if it did not finish, run codex mcp login ainecto).
• To add AiNecto's working rules to a repository, run npx -y ainecto@latest init from its root. It does not ask for a role or a project.
• A server added during a session is not available in that session. Keep working through the CLI: npx -y ainecto@latest tools list and npx -y ainecto@latest tools call ' '. A new session loads the MCP tools.
• If a result names a tool that is not in your tool list, the session started before that tool was added — start a new session or call it through the CLI as above.
• Claude Code's auto mode may block running an external package with npx. If it does, ask the user to allow the command.
• ChatGPT, Claude and other apps: see https://ainecto.com/docs/get-started/connect-your-agent/

Set up this machine

npx -y ainecto@latest setup              # sign in, check, connect Claude Code · Cursor · Codex

npx -y ainecto@latest setup --dry-run # show what it would do — no sign-in, no changes npx -y ainecto@latest setup --local # connect through the local relay instead (see below) npx -y ainecto@latest setup --undo # remove the connections setup made (sign-in stays) npx -y ainecto@latest status # who is signed in, your AiNecto role, what is connected npx -y ainecto@latest doctor # what is missing, and the one command that fixes each item

setup connects each client separately and reports connected, updated, kept (someone else's ainecto entry, left untouched), not installed, or failed; if any client fails it says «partial» and exits 1:

• Claude Code — claude mcp add --transport http -s user ainecto https://ainecto.com/mcp (user scope). Sign in with /mcp in a session.
• Cursor — merges "ainecto": { "url": "https://ainecto.com/mcp" } into ~/.cursor/mcp.json, keeping your other servers. Cursor asks you to sign in from its MCP settings.
• Codex — codex mcp add ainecto --url https://ainecto.com/mcp. Codex starts its sign-in right away (a browser tab opens; setup passes Codex's output, with the sign-in link, through to stderr). If that did not finish within 90 seconds, Codex shows as failed but stays connected — run codex mcp login ainecto (re-running setup says the same).

With --env dev (or --endpoint) the address is that environment's. The server address has no version to pin: a server update reaches every agent at once. Entries an older setup wrote (npx -y @ainecto/mcp@ , with or without --role) are rewritten to the server address when you re-run setup; setup --undo removes either kind.

setup --local registers the local relay instead — npx -y @ainecto/mcp@ (stdio, pinned to the CLI version), which uses this machine's one ainecto sign-in for every agent. Use it only when an agent cannot sign in to the server address by itself; running setup again without --local moves back to the server address.

Your AiNecto role (your job, set in AiNecto's account settings) is shown by setup and status; AI uses it to pitch explanations — it does not change permissions.

Set up a repository (optional)

npx -y ainecto@latest init               # .ainecto/HARNESS.md, an AGENTS.md block (and CLAUDE.md if present), .ainecto/config.json

npx -y ainecto@latest init --mcp # also .mcp.json (Claude Code) and .cursor/mcp.json (Cursor), with the server address npx -y ainecto@latest init --mcp --local # the same files with the local relay instead npx -y ainecto@latest init --dry-run # the same plan, nothing written npx -y ainecto@latest init --undo # remove what init wrote npx -y ainecto@latest init --agent tester # name the agent working in this folder (see below)

• --agent names the agent that works in this folder. It writes the name to .ainecto/agent.local (keep it out of git) and puts it in .mcp.json, .cursor/mcp.json and .codex/config.toml — the server address entries get the header X-AiNecto-Agent-Name, the local relay gets --agent . Re-running init keeps the name. ainecto tools call … run in this folder sends the same name. The server checks the name; a name it refuses stops init before any file is written. .codex/config.toml is written only when it does not exist yet (or init wrote it); Codex reads it only in a trusted project.

• init fetches the rules from the server — --dry-run too, so the plan is the real one. If it cannot (not signed in, offline), it says which files would get this package's default text instead.
• If this machine is not signed in yet, init opens the browser once (--dry-run never does). The sign-in URL is printed first (with --json, as one JSON line on stderr: {"event":"login_url","url":…}).
• It stops when run from a sub-folder of a git repository, and tells you the root.
• --mcp writes the server address, like setup: .mcp.json gets "ainecto": { "type": "http", "url": "https://ainecto.com/mcp" } (Claude Code needs the type) and .cursor/mcp.json gets "ainecto": { "url": "https://ainecto.com/mcp" }. Each agent signs in by itself the first time. --local writes the pinned local relay instead (see Connector Mode).
• Repositories set up earlier (.mcp.json with npx -y @ainecto/mcp…, with or without --role): re-run npx -y ainecto@latest init. It rewrites the existing ainecto entry to the server address (or, with --local, to the relay pinned to this version without --role), and drops the old project field from .ainecto/config.json (unless you changed it). An ainecto entry pointing somewhere else is left alone. Until then the old entry keeps working: --role is accepted and ignored. Old flags (--role, --project, --project-name, --yes) are ignored with a one-line note.

Commands

Prefer npx -y ainecto@latest . To install once instead, use npm install -g ainecto — but install only one of ainecto, @ainecto/mcp and @ainecto/cli globally: they are the same code and all ship the ainecto command, so a second global install conflicts. (@ainecto/mcp also carries mcp, the bridge.)

ainecto auth login          # once per machine (and per --env) — `setup` does this for you

ainecto auth status ainecto auth logout

ainecto tools list ainecto tools call list_projects --json ainecto tools call erd_apply_changes -f changes.json --json cat payload.json | ainecto tools call erd_apply_changes --json

ainecto projects list ainecto erd apply-changes -f erd-operations.json --yes

Tool names are the server's own names (list_projects, erd_apply_changes, …). Your AI client shows them with its own prefix, for example mcp__ainecto__list_projects in Claude Code; the CLI does not use that prefix. A tool name that starts with the server's older mcp__ainecto__ prefix is still accepted.

Every command takes --env dev for https://dev.ainecto.com/mcp. Endpoint resolution priority:

1. --endpoint
2. AINECTO_MCP_ENDPOINT
3. --env dev
4. production default, https://ainecto.com/mcp

Endpoint URLs must use https:. Plain http: is accepted only for localhost loopback targets such as 127.0.0.1. When AINECTO_TOKEN is set, the CLI only sends it to the default prod/dev endpoints unless AINECTO_ALLOW_CUSTOM_ENDPOINT_TOKEN=1 is set for an explicitly trusted custom endpoint.

The commands are ainecto and mcp (which npx -y @ainecto/mcp runs). The AINECTO_* environment variables above are the only names for those settings — do not guess another prefix.

Generated Friendly Commands

Every checked-in generated catalog tool is reachable through its deterministic command path. Scalar schema fields are exposed as flags, with both kebab-case and schema-case accepted:

ainecto documents list --project-uuid <projectUuid>

ainecto documents list --projectUuid

Array or object payloads use the first-party CLI JSON payload reader:

ainecto documents create -f create-documents.json

cat erd-operations.json | ainecto erd apply-changes --json

Destructive generated commands prompt in human mode unless --yes is supplied. In --json mode they fail with a structured error unless --yes is present.

Attachment file upload is available through a bespoke command that performs the upload-token, raw PUT, and attachment registration flow:

ainecto attachments upload --document-uuid <documentUuid> ./diagram.png ./notes.pdf

The generated request_upload_token and upload_attachments paths remain raw MCP argument-contract commands and do not read local files.

Inbox polling — for a scheduler (cron, launchd) that wakes an agent only when something is new. Exit codes: 0 new items, 3 nothing new, 1 error, 2 usage error. notifications poll saves the batch to the cursor file before printing it and prints the same batch again until notifications ack (run it only after the agent handled the batch). agent-todos poll --only-new exits 0 only for to-dos it has not seen before (kept in the seen file). Both take --workspace and --project , each repeatable: any of the given workspaces AND any of the given projects. Each filter is its own notification stream, so use one cursor file per filter.

ainecto notifications poll --direct-only --cursor-file ~/.ainecto/inbox.cursor --json > /tmp/inbox.json \

&& claude -p "Summarize these AiNecto notifications: $(cat /tmp/inbox.json)" \ && ainecto notifications ack --cursor-file ~/.ainecto/inbox.cursor ainecto agent-todos poll --only-new --seen-file ~/.ainecto/todos.seen --json > /tmp/todos.json \ && claude -p "Review these AiNecto to-dos and only summarize them: $(cat /tmp/todos.json)"

The server tools behind them (list_notifications, list_agent_todos, update_agent_todos, list_history) are generated commands too (ainecto notifications list, ainecto agent-todos list, ainecto agent-todos update -f …, ainecto history list) once the server exposes them.

Terminal Sessions

ainecto term keeps terminal sessions running after you close the terminal window — no tmux or cmux needed. A background process, started on demand, owns each session and keeps its screen, so agents and scripts can type into a session and read its screen, and you can attach from any terminal app. It runs on this machine only; it does not use your AiNecto sign-in.

ainecto term new api --cwd ~/code/api -- claude   # start a session (without a command: your login shell)

ainecto term ls [--json] ainecto term send api "run the tests" # types the text, without Enter ainecto term key api enter