qivo

Automation & AI — the REST API and the MCP server

Two surfaces, one credential model: whoever calls is a user (§14).

The website, MCP and REST call a work item a task, and a collection tasks. MCP uses get_task, create_task, update_task and delete_task for one task, and list_tasks for a collection. REST uses /v1/tasks for the collection and /v1/tasks/{ref} for one task. These names refer to the same tasks, with the same permanent QN-<number> IDs.

Both surfaces read and write a task's reviewer as reviewer_id (results also carry reviewer_name), under the same eligibility rules as assignee_id. A task created in or moved into review gets the project's review time as its remaining hours unless the same call sends hours (§7). Their assignee filters keep matching the stored assignee, also while a reviewer owns the task.

Guides for agents#

The public website provides three starting points for an assistant:

  • llms.txt is a short index of the product guides, grouped by connection, task work and planning.
  • skill.md explains how to find and update tasks, select valid assignees, verify changes and choose between MCP, REST and the browser.
  • auth.md explains OAuth connections, personal tokens and agent keys, including organization scope and revocation.

The website footer's For agents link opens the operating guide. Give an assistant that URL when it needs instructions; loading these public files does not sign it in or grant project access.

REST API — for scripts and automation#

A request authenticates as an agent user with its qva_ key. What it may reach is simply the projects that agent has a role on — Viewer reads, User and Lead read and write — so there is no second permission list to keep in step with the real one. The API covers projects, users, tasks (list/filter/search, create, patch, delete — including archive / restore, with archived tasks excluded from listings unless asked for) and comments, with the app's field validation (statuses, priorities, the 80-character title cap, week pairing) — and anything the agent can't read is a plain 404, indistinguishable from nonexistent. Archived projects follow the app: the project list shows the live ones (?archived=true for the other side), an archived project's tasks are out of the task list unless you name the project, and creating a task in one is refused by name.

  • A viewer role reads and nothing more, and a grant is per project, so an agent reaches exactly the projects it was added to and nothing else in the organization's work — least privilege at a grain most PM APIs don't offer.
  • API writes are signed: the agent is the actor in the activity feed and the author of comments it posts. Attempts to claim a different author are rejected — you are only ever yourself.

MCP server — for AI assistants#

OAuth is the preferred way to connect your assistant to Qivo's MCP server. An assistant that supports it can connect without copying a token. Add https://api.qivo.io/mcp as a remote MCP server in the assistant, start its connection flow, and sign in to Qivo. The approval screen identifies the app and organization and explains its requested access. The default request includes reading, changes and automatic renewal. Allow changes starts on for a write request; turn it off to approve reading only. Choose Connect to return to the assistant, or Cancel to refuse. Approve only a connection you started in the intended assistant; the app name is supplied by its client.

Connected apps under Settings → User account → MCP access lists approved connections, their organization and access. Delete asks for confirmation, stops subsequent requests and automatic renewal, and removes that connection from the list. Previously disconnected connections can also be deleted. It affects that connection only. Connecting again requires a new approval. OAuth clients must support authorization code with PKCE and dynamic client registration; Client ID Metadata Documents and device-code flows are not implemented.

If the assistant lacks compatible OAuth support, or you prefer manual setup, clients that accept a custom Authorization header can use Personal access tokens from the secondary section of MCP access; these tokens do not expire automatically, so revoke them when no longer needed. For each new token, the page generates a ready-made claude mcp add … command. The MCP access box opens with Connect with OAuth, for an agent acting on your behalf: copy the server address into your assistant's MCP settings, start the connection from your AI agent, sign in when the Qivo sign-in window appears, then approve the connection. The box also points to the Users page, where organization admins create agent users. An agent user connects with its own key instead (§14). Claude Code, Claude Desktop or any MCP client then operates Qivo conversationally with twelve tools: list teams / projects / users / project users / tasks, get task, list & add comments, create / update / delete tasks, and set someone's plannable week. list_projects shows the live projects and takes archived: true for the ones that have been put away; an archived project's tasks stay out of list_tasks unless you name the project, and creating a task in one comes back with a sentence saying which project to restore.

The connection acts as you: every call runs under your permissions — the assistant reads within your project access and writes only where you could, with an additional read-only ceiling when you approve reading only. One qualification since guests exist: a credential belongs to one seat and stays inside that organization, so a token made in your own organization never reaches a project someone else shared with you. The current settings page creates personal tokens for your home account (or the first guest account when you have no home organization), without an organization selector. OAuth shows that same home organization during approval and binds the connection to it permanently, even if your home account later changes. Use the browser for guest work, or ask the other organization's admin for an agent with access to the required projects. Its task writes appear in the activity feed under your name, labeled "via MCP"; comments it posts are simply your comments (a comment is its own feed entry).

Manual tokens and agent keys share the same credential hygiene: secrets shown once and stored hashed, a display prefix plus created / last-used dates on every row (the at-a-glance "is this integration still alive?" audit), and two-click revocation that cuts access immediately. OAuth credentials are delivered to the assistant directly and stored hashed. Access tokens expire and approved offline access lets clients renew them automatically. Disconnecting or making the account inactive prevents further access.

✦ What sets this apart — A first-party MCP server as a co-equal product surface: AI assistants get per-user permission fidelity (no over-privileged bot accounts, no "the integration sees more than I do"), one-paste setup, and attributed task writes. Combined with the agent-user REST tier, human edits, team automation and personal AI are visibly distinct actors.