Connect Claude to Vivotics (MCP)

Vivotics ships an MCP server, so Claude (and any MCP-compatible AI app) can work inside your workspace: list projects, create tasks, move kanban cards, assign teammates, post comments and add subtasks — straight from a conversation.

MCP (Model Context Protocol) is the open standard AI assistants use to call external tools. You run a tiny local server that bridges your AI app to your Vivotics workspace over the official API.

How permissions work (read this first)

The MCP server authenticates with a personal API token. Every action runs as the user who owns the token, and Vivotics enforces their role exactly like the web app:

• An admin's token can create projects, assign anyone, see everything their role sees.
• An employee's token only sees and does what their role allows — anything else is refused by the server.
• Read-only mode: set VIVOTICS_READONLY=1 and the connection can look but never write, regardless of the user's role.
• Tokens are valid for about a year and stop working the moment the user is deactivated.

Give every teammate their own token. Never share one token across people — that defeats the permission model and muddles the audit trail.

Prerequisites

• Node.js 18 or newer (node --version to check)
• A Vivotics account (any role; superadmin accounts are intentionally blocked from the API)

Step 1 — Download and install the server

Download vivotics-mcp.zip and unzip it somewhere permanent, e.g. ~/vivotics-mcp. Then install its two dependencies:

cd ~/vivotics-mcp
npm install

Step 2 — Get your personal token

node get-token.mjs [email protected]

It prompts for your Vivotics password (not echoed, never stored) and prints a token. Keep it like a password.

Recommended: store it in a small env file the server auto-loads, so it never sits inside app configs:

mkdir -p ~/.cubitrek-secrets
printf 'VIVOTICS_API_TOKEN=PASTE_YOUR_TOKEN_HERE\n' > ~/.cubitrek-secrets/vivotics-mcp.env
chmod 600 ~/.cubitrek-secrets/vivotics-mcp.env

(Alternatively, pass the token via the env block of your MCP client config below.)

Step 3 — Connect your AI app

Claude Code (CLI)

claude mcp add vivotics -- node ~/vivotics-mcp/index.mjs

Or per-project, in a .mcp.json at the project root:

{
  "mcpServers": {
    "vivotics": {
      "command": "node",
      "args": ["/absolute/path/to/vivotics-mcp/index.mjs"]
    }
  }
}

Claude Desktop

Open the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server and restart Claude Desktop:

{
  "mcpServers": {
    "vivotics": {
      "command": "node",
      "args": ["/absolute/path/to/vivotics-mcp/index.mjs"],
      "env": {
        "VIVOTICS_API_TOKEN": "your-token-here"
      }
    }
  }
}

(Skip the env block if you created the secrets file in Step 2.)

Any other MCP client

Configure a stdio server with command node, argument /path/to/vivotics-mcp/index.mjs, and the environment variables below. Cursor, Windsurf, Zed and other MCP-compatible tools all follow this same pattern.

Environment variables

What Claude can do once connected

Read: who am I, list projects, project detail, list/filter tasks, my tasks, task detail, board columns, team members, clients.

Write: create project, create task (with assignees, priority, dates), update task (retitle, reschedule, reassign, move between board columns, mark complete), comment on task, add subtask.

Try prompts like:

• "List my open tasks in Vivotics and flag anything overdue."
• "Create a project 'Website revamp' starting Monday with tasks for design, build and QA, assign design to Sara, due in two weeks."
• "Move task 214 to Doing and comment that development started."
• "Summarize the Marketing project: what's done, what's stuck."

Revoking access

Deactivate the user in Vivotics (or change their password and re-issue tokens) and their token stops working. To pull one machine's access, just delete the token from that machine's env file or client config.

Troubleshooting

• "VIVOTICS_API_TOKEN is not set" — the server can't find your token: create the secrets file from Step 2 or add the env block to your client config.
• 401 errors — token expired or the user was deactivated; run get-token.mjs again.
• 403 on a write — your role doesn't have that permission in Vivotics; ask your workspace admin.
• "Sorry this app is not built for superadmin" — use a workspace (company) account, not the platform superadmin.
• Moving a task fails — board column ids are per-workspace; ask Claude to check the board columns first (it has a tool for that).