Developers — Kapvel API & MCP

Quickstart: connect your AI assistant

Create a token. In your workspace open Settings → API & MCP access → Create token (sign in first). Pick read-only or read & write, optionally restrict it to one workspace, and copy the kpv_... value — it is shown exactly once.
Add the server. Use the one-click Cursor button below, or copy the command for Claude Code, Codex, or Claude Desktop.
Ask away.“What is assigned to me?”, “Create a bug in ENG about the broken login”, “Log 2h on ENG-42”, “Start the next sprint”.

Your API token (optional — personalizes the button and snippets)

Pasted tokens stay in your browser; this page never sends them anywhere.

One click: installs the Kapvel MCP server with your token in Cursor.
Nothing happening? Use the web installer or the Cursor (manual) tab below.

claude mcp add --transport http kapvel https://kapvel.com/api/mcp --header "Authorization: Bearer YOUR_TOKEN"

Run in a terminal; Claude Code picks the server up immediately.

What can you ask?

Once connected, your assistant can handle anything the tools cover — click a prompt to copy it:

Authentication

Both surfaces authenticate the same way: a personal access token in the Authorization header.

Authorization: Bearer kpv_your_token_here

Tokens act as you. A request can only read or change what your account can — every query runs through the same database-level permission rules as the app (workspace membership, private projects, doc sharing, role checks).
Scopes. read tokens can only query; write tokens can also create, update, and delete.
Workspace restriction. A token can be limited to a single workspace; requests touching anything else are rejected.
Lifecycle. Optional expiry, revocable at any time, stored hashed (we cannot show a token twice), up to 25 active tokens per account.

Rate limits

Each token gets 120 requests per minute and 5,000 requests per hour, enforced atomically in the database. Every response carries the current budget:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 42        # seconds until the window resets
Retry-After: 42              # only on 429 responses

When you exceed a limit the API answers 429 rate_limited; back off for Retry-After seconds. Repeated failed authentication attempts are throttled separately.

MCP server & tools

The MCP endpoint speaks Streamable HTTP at https://kapvel.com/api/mcp — no extra gateway or session store needed. Tools marked read work with read-only tokens; tools marked write need write scope.

You & workspaces

get_meread

Returns the authenticated user (the token's owner), the token scopes, and the workspaces they belong to with their role in each.

list_workspacesread

Lists the workspaces (organizations) the user belongs to, with slug, plan and role. Workspace slugs identify workspaces in other tools.

list_workspace_membersread

Lists the people in a workspace with their name, email, and role (admin, member, or customer). Use emails to reference people in other tools (e.g. assignee).

list_my_notificationsread

Lists the user's inbox notifications (assignments, comments, mentions, status changes), newest first.

Projects

list_projectsread

Lists the projects you can access, with key, type (kanban, scrum, or service desk), and lead. Project keys (like ENG) identify projects in other tools.

get_projectread

Returns one project with its workflow statuses, work-item types, labels, open sprints, and releases. Call this before creating or updating issues to learn the valid status/type/label names.

create_projectwrite

Creates a project with default To Do / In Progress / Done statuses. The key must be 2-10 uppercase letters/digits starting with a letter.

Issues

search_issuesread

Searches issues (tasks, stories, bugs, epics) across your workspaces with filters for project, text, status, assignee, type, sprint, label, priority, and recency. Returns compact issue summaries.

get_issueread

Returns one issue in full: description (as text), assignee, labels, sprint, subtasks, links to other issues, and up to 50 comments.

create_issuewrite

Creates an issue in a project. Only project and title are required; type/status/priority default sensibly. Returns the new issue key.

update_issuewrite

Updates any combination of an issue's fields: title, description, status (by name), priority, assignee, sprint, parent, release, labels, points, and dates. Pass null to clear a nullable field. Returns the updated issue.

delete_issuewrite

Permanently deletes an issue. Only workspace admins or the issue's reporter may delete.

link_issueswrite

Creates (or removes) a typed link between two issues: blocks, relates_to, or duplicates.

Comments

list_commentsread

Lists an issue's comments in chronological order, with author and plain-text body.

add_commentwrite

Adds a comment to an issue as the token's owner. Set internal=true on service-desk issues for agent-only notes.

update_commentwrite

Edits a comment you authored (replaces its text).

delete_commentwrite

Deletes a comment (yours, or any comment if you are a workspace admin).

Sprints

list_sprintsread

Lists a project's sprints with state (future, active, closed), dates, and points.

create_sprintwrite

Creates a future sprint in a scrum project. Assign issues to it with update_issue, then start it with start_sprint.

start_sprintwrite

Starts a future sprint, recording committed points. Defaults to a two-week window starting now.

complete_sprintwrite

Completes an active sprint. Unfinished issues move to the backlog, or to another open sprint via move_open_issues_to.

Docs

list_spacesread

Lists the wiki spaces in a workspace. Spaces contain pages, whiteboards, spreadsheets, and presentations.

list_docsread

Lists docs in a workspace or space, newest first, with optional full-text search across titles and page content.

get_docread

Returns a doc with its content as plain text (pages only; whiteboards and spreadsheets return metadata).

create_docwrite

Creates a wiki page in a space from plain text (lines starting with - become bullets). Default access lets the whole workspace edit it.

update_docwrite

Updates a doc's title, access, archived flag, or (for pages never edited collaboratively) replaces its content.

delete_docwrite

Permanently deletes a doc (and its children).

Time tracking

list_time_entriesread

Lists tracked time filtered by issue, person, and date range, with a summed total. Dates are YYYY-MM-DD.

log_timewrite

Logs worked time on an issue for the token's owner, e.g. duration "1h 30m" (a day counts as 8h).

start_timerwrite

Starts a live timer on an issue for the token's owner (stops any other running timer first).

stop_timerwrite

Stops the running timer and records the elapsed time.

Releases

list_releasesread

Lists a project's releases (fix versions) with status and dates. Assign issues to a release with update_issue.

create_releasewrite

Creates a release in a project (project leads and admins only). Dates are YYYY-MM-DD.

REST API

Prefer plain HTTPS? The same operations are exposed under https://kapvel.com/api/v1. Issues accept keys (ENG-42) or UUIDs; projects accept keys (ENG) or UUIDs; list endpoints take limit (max 100) and offset.

# Everything assigned to me, still open
curl "https://kapvel.com/api/v1/issues?assignee=me&status_category=in_progress" \
  -H "Authorization: Bearer $KAPVEL_API_TOKEN"

# File a bug
curl -X POST "https://kapvel.com/api/v1/projects/ENG/issues" \
  -H "Authorization: Bearer $KAPVEL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Login button unresponsive", "type": "bug", "priority": "high"}'

# Move it to Done
curl -X PATCH "https://kapvel.com/api/v1/issues/ENG-42" \
  -H "Authorization: Bearer $KAPVEL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "Done"}'

GET/api/v1/meCurrent user, scopes, and workspaces

GET/api/v1/me/notificationsYour inbox notifications

GET/api/v1/workspacesWorkspaces you belong to

GET/api/v1/workspaces/{slug}/membersPeople in a workspace

GET/api/v1/projects?workspace=List projects

POST/api/v1/projectsCreate a project

GET/api/v1/projects/{key}Project with statuses, types, labels, sprints

GET/api/v1/projects/{key}/issuesSearch issues in a project (filters as query params)

POST/api/v1/projects/{key}/issuesCreate an issue

GET/api/v1/issues?text=&assignee=meSearch issues across workspaces

GET/api/v1/issues/{key}Full issue: description, comments, links, subtasks

PATCH/api/v1/issues/{key}Update fields, status, assignee, labels...

DELETE/api/v1/issues/{key}Delete an issue

GET/api/v1/issues/{key}/commentsList comments

POST/api/v1/issues/{key}/commentsAdd a comment

POST/api/v1/issues/{key}/linksLink two issues (blocks, relates_to, duplicates)

PATCH/api/v1/comments/{id}Edit your comment

DELETE/api/v1/comments/{id}Delete a comment

GET/api/v1/projects/{key}/sprintsList sprints

POST/api/v1/projects/{key}/sprintsCreate a sprint

POST/api/v1/sprints/{id}/startStart a sprint

POST/api/v1/sprints/{id}/completeComplete a sprint

GET/api/v1/projects/{key}/releasesList releases

POST/api/v1/projects/{key}/releasesCreate a release

GET/api/v1/spacesList doc spaces

GET/api/v1/docs?query=List and search docs

POST/api/v1/docsCreate a wiki page from text

GET/api/v1/docs/{id}Read a doc as plain text

PATCH/api/v1/docs/{id}Update title, content, access, archived

DELETE/api/v1/docs/{id}Delete a doc

GET/api/v1/time-entries?user=me&from=List tracked time

POST/api/v1/time-entriesLog time ({"issue", "duration": "1h 30m"})

POST/api/v1/timerStart/stop a live timer ({"action": "start", "issue"})

Errors

Errors are JSON with a stable code and a human-readable message:

{ "error": { "code": "insufficient_scope", "message": "This token is read-only..." } }

400invalid_inputValidation failed; the message says which field and why.

401invalid_tokenMissing, malformed, revoked, or unknown token.

401token_expiredThe token passed its expiry date.

403insufficient_scopeWrite attempted with a read-only token.

403workspace_restrictedThe token is restricted to a different workspace.

403permission_deniedYour role does not allow this action.

404not_foundThe resource does not exist — or your permissions hide it.

429rate_limitedToo many requests; wait for Retry-After seconds.

Notes & roadmap

Every list is paginated: limit caps at 100 per page, offset pages further, and responses carry has_more. Long text fields and MCP tool outputs are truncated with explicit markers — no single call can dump a whole workspace.
Rich text (descriptions, comments, doc pages) is exchanged as plain text; lines starting with - become bullet points.
Pages edited collaboratively in the app cannot have their content replaced through the API (title, access, and archive still work) — this protects live editing sessions.
Not yet exposed (coming in a later wave): QA test runs, approvals, automation rules, service-desk portal actions, and file attachments.
Questions or a use case we should support? Talk to us.

Your workspace, scriptable — API & MCP