MCP Integration

Connect Gravitask to AI Tools

Use the Model Context Protocol (MCP) to let AI assistants manage your tasks, projects, and time tracking directly in Gravitask.

What AI tools can do with Gravitask

  • Plan work: tasks, batches of 50, dependencies, milestones
  • Search everything, including the wiki
  • Report on time, workload, and project progress
  • Run and inspect your automations
  • Comment, tag, attach links, and log time
  • Preview changes before committing them

Prerequisites

  1. 1A Gravitask account. Create one for free.
  2. 2A way to authenticate: OAuth (built in, used by Claude and ChatGPT connectors) or an API key from Settings > API & MCP for CLI and IDE clients. The section below helps you choose.

Using Claude or ChatGPT on the web?

Web and desktop chat apps connect with one-click OAuth instead of the API-key configuration below. Follow the dedicated walkthroughs:

OAuth or API key: which should you use?

Both reach the same MCP server. The right choice depends on the client and how much access you want to grant.

SituationUse
Claude.ai, Claude Desktop, ChatGPTOAuth
Claude Code, Cursor, VS Code, other CLIs and IDEsAPI key
A bot or script with one job (for example logging time)API key with tool groups
Analysis and reporting onlyEither, restricted to read

Choosing a scope

Grant the least access that does the job. Read only covers browsing, search and every report. Read & Write adds creating and updating tasks, comments, time and wiki pages. Full access additionally allows permanent deletion and is off until a workspace admin enables it. API keys can also be limited to tool groups (Read, Write, Admin, Wiki, Time tracking, Automations, Reporting) when you create them.

Quick Setup: API key clients

This universal configuration works with most MCP-compatible AI tools. Set GRAVITASK_API_KEY to your actual API key before starting the client.

{
  "mcpServers": {
    "gravitask": {
      "type": "http",
      "url": "https://app.gravitask.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GRAVITASK_API_KEY}"
      }
    }
  }
}

Setup by AI Client

Expand the section for your AI tool to see specific setup instructions.

Available Tools

Gravitask exposes 67 tools through MCP, grouped by category. Tool names carry a gravitask_ prefix; older unprefixed names keep working for existing setups. Availability depends on your plan, workspace permission level, and any per-key restrictions.

Read & browse

ToolPermission
gravitask_list_projects

List projects in the workspace with task/member counts.

Read
gravitask_get_project

Get one project with its members, sections (status columns), and task count.

Read
gravitask_list_tasks

List task summaries in one project, filterable by status (TODO | IN_PROGRESS | REVIEW | DONE, DONE means Closed), assignee user id, priority (NONE | LOW | MEDIUM | HIGH | URGENT), title substring, or overdue.

Read
gravitask_get_task

Get one task in full: description (as markdown), subtasks, comments, tags, attachments, custom fields, time entries.

Read
gravitask_create_task_preview

Dry-run of create_task / plan_task: runs every validation (project, assignee membership, section, parent, WIP limits) and reports the exact effective placement, including the auto-matched section, WITHOUT creating anything.

Read
gravitask_list_comments

List comments on a task (oldest first) with author and markdown content.

Read
gravitask_search

Ranked full-text search across tasks, projects, comments, and wiki pages in the workspace (typo-tolerant, matches descriptions too).

Read
gravitask_get_workspace

Get the connected workspace: name, project count, and members with roles.

Read
gravitask_list_members

List workspace members (id, name, email, role), the source of valid assignee_id / user_id values.

Read
gravitask_list_tags

List the tags of one project (tags are project-scoped).

Read
gravitask_list_dependencies

List a task's dependency edges in both directions: what it depends on (tasks or milestones, with FS/SS/FF/SF kind and lag) and what depends on it.

Read
gravitask_list_milestones

List a project's milestones (id, name, date, completed) ordered by date.

Read
gravitask_list_sections

List a project's sections (board columns) in display order, the source of valid group_id values for create_task / update_task.

Read
gravitask_list_my_tasks

Answer "what is on my plate" in ONE call: tasks across ALL projects in the workspace for the connected user (or another member via assignee_id), filterable by status, overdue, or due_before, ordered by due date.

Read
gravitask_get_task_activity

A task's change history: who did what and when (creation, field changes with from→to values, comments), including changes made through MCP, which are recorded in the same stream.

Read
gravitask_list_custom_fields

List a project's custom field definitions (id, name, type TEXT | NUMBER | SINGLE_SELECT | MULTI_SELECT | DATE | CHECKBOX | URL | FORMULA, required flag, and options for selects).

Read
gravitask_list_attachments

List a task's attachments (file name, URL, size, source, uploads, cloud files, and links).

Read
gravitask_list_collaborators

List the people following a task besides the assignee (reviewers/watchers who get notified of changes).

Read
gravitask_list_notifications

The connected user's own notification inbox (never anyone else's), newest first, with unread_only filter, the "what needs my attention" triage loop.

Read
gravitask_get_recurrence

Inspect a task's recurring-series rule: the RFC 5545 RRULE, a human-readable description, timezone, paused state, and which occurrence this task is.

Read
gravitask_list_portfolios

List the workspace's portfolios with their member projects, the roll-up grouping for exec-level questions.

Read
gravitask_list_goals

List the workspace's goals (OKR-style) with status (ON_TRACK | AT_RISK | OFF_TRACK | ACHIEVED | MISSED | PARTIAL), progress percent, and date range.

Read
gravitask_get_goal

One goal with its task-completion roll-up computed across the linked projects (total/completed per project and overall progress percent).

Read
gravitask_list_forms

List a project's intake forms (name, public slug, active state, submission count).

Read
gravitask_list_lookup_tables

List the workspace's lookup tables (reference data used by automations): columns, key column, and row counts.

Read
gravitask_get_lookup_table

Read a lookup table's rows (as key→value records) with cursor pagination, the reference data automations resolve against.

Read
gravitask_get_critical_path

Compute the critical path of a project from task dependencies: the chain of tasks driving the end date, plus per-task float.

Read

Create & update

ToolPermission
gravitask_create_task

Create a task in a project.

Write
gravitask_plan_task

Workflow tool: create a task AND assign it, tag it (tags are created if missing), schedule it, and leave an opening comment in a single call, instead of chaining create_task + add_tag_to_task + add_comment.

Write
gravitask_create_tasks

Batch create up to 50 tasks in one project in a single call, use for sprint imports or mass triage instead of many create_task calls.

Write
gravitask_update_tasks

Batch update up to 50 tasks in one call, bulk re-prioritise, re-assign, or re-schedule without N round-trips.

Write
gravitask_complete_tasks

Batch close up to 50 tasks in one call (sets status DONE, fires the same automations as closing in the app).

Write
gravitask_update_task

Update task fields (title, markdown description, status, priority, assignee, dates, section).

Write
gravitask_complete_task

Close a task (sets status DONE and stamps completedAt).

Write
gravitask_move_task

Move a task to another project and/or change its status.

Write
gravitask_add_comment

Add a comment to a task.

Write
gravitask_create_tag

Create a tag in a project (upsert, an existing tag with the same name is returned, not duplicated).

Write
gravitask_add_tag_to_task

Attach a tag to a task by tag_id or tag_name (looked up in the task's project).

Write
gravitask_remove_tag_from_task

Detach a tag from a task by tag_id.

Write
gravitask_create_dependency

Make one task depend on another task OR on a milestone (exactly one of depends_on_task_id / depends_on_milestone_id).

Write
gravitask_delete_dependency

Remove a dependency edge by its UUID (get it from list_dependencies).

Write
gravitask_create_milestone

Create a dated milestone in a project, the anchor points that dependencies and the critical path compute against.

Write
gravitask_update_milestone

Update a milestone's name, date, description, color, or completed flag.

Write
gravitask_create_section

Add a section (board column) to a project, appended after the existing columns.

Write
gravitask_update_section

Rename or recolor a section, or reorder it by anchoring after_section_id / before_section_id (sections in the same project).

Write
gravitask_set_custom_field

Set a custom field value on a task: a string for most types, an array of options for MULTI_SELECT, null to clear.

Write
gravitask_attach_link

Attach an external http(s) URL to a task as a link attachment (docs, designs, PRs, cloud files) so supporting context lives on the task.

Write
gravitask_add_collaborator

Add a workspace member as a collaborator (watcher) on a task, they are notified like in the app.

Write
gravitask_remove_collaborator

Remove a collaborator from a task.

Write
gravitask_mark_notification_read

Mark one of the connected user's notifications as read after triaging it.

Write
gravitask_set_recurrence_paused

Pause or resume future occurrence generation for a task's recurring series.

Write

Wiki

ToolPermission
gravitask_list_wiki_pages

List wiki pages in the workspace as lean summaries (id, shortId, title, state, scope, updatedAt).

Read
gravitask_search_wiki_pages

Full-text search across wiki page titles and bodies with permission filtering, better than list_wiki_pages when you do not know the exact title.

Read
gravitask_get_wiki_page

Read one wiki page in full (title, plain-text body, owner, verification state) by its UUID.

Read
gravitask_create_wiki_page

Create a wiki page from plain text.

Write
gravitask_update_wiki_page

Update a wiki page title, plain-text body, or owner.

Write
gravitask_verify_wiki_page

Mark a wiki page as verified (optionally until expires_at, ISO 8601), signalling the content is accurate.

Write

Time tracking

ToolPermission
gravitask_list_time_entries

List time entries filtered by task, project, user, or ISO date range, the building block for timesheet and utilisation questions.

Read
gravitask_log_time

Log manual time against a task in minutes, optionally billable and dated (defaults to today).

Write
gravitask_time_summary

Aggregate logged time by project, user, or day over an optional date range, answers "how much time did we log".

Read

Automations

ToolPermission
gravitask_list_automations

List the workspace's automation rules (id, name, enabled, scope, trigger type, run stats).

Read
gravitask_get_automation

Get one automation rule in detail: trigger, conditions, step count, run stats, and the 5 most recent runs with status and errors.

Read
gravitask_run_automation

Fire an automation rule with a manual trigger (triggerType "manual" in list_automations), the same quota-gated, audited path as clicking Run in the app.

Write
gravitask_suggest_automation

Surface AI-generated automation rule suggestions for a project.

Write

Reporting

ToolPermission
gravitask_workload_by_assignee

Open and overdue task counts per assignee across the workspace (or one project), answers "who is overloaded" for rebalancing decisions.

Read
gravitask_project_progress

On-track signal for one project: total / completed / overdue task counts, completion rate percent, and a per-status breakdown.

Read

Admin

ToolPermission
gravitask_delete_task

PERMANENTLY delete a task and its subtask links.

Write

Safe agent writes: preview, undo, approvals

Writes are on for every plan, so Gravitask gives you three layers of control over what an agent changes. Nothing here is required, and a workspace that leaves it all off behaves exactly as before.

Preview, then commit

The recommended agent workflow for anything consequential: propose the change, show it to the person, then commit. create_task_preview reports the exact task that would be created; update_task, update_tasks and move_task take preview: true to return the before and after without touching anything. Each preview names the tool to call to commit.

Undo

Every agent write is recorded as a reversible changeset. Call undo_changeset to revert one change or a whole batch, or use the Revert buttons under Settings, API & MCP. If a person edited the item since, the undo is refused rather than overwriting their work.

Approvals (Business)

For compliance-driven teams, a workspace admin can require approval for chosen tool groups (for example deletes or wiki writes). Covered writes are held as pending changes and applied only when an admin approves them, attributed to whoever requested the change. Off by default.

Troubleshooting

"Connection refused"

Check that GRAVITASK_API_KEY is set in the same shell that starts the AI client. You can regenerate a key from Settings > API & MCP in the Gravitask app.

"Permission denied"

Verify that MCP is enabled for your workspace in Settings > Integrations. Workspace admins control this setting.

"Tool not found"

Some tools may be disabled by your workspace admin. Check Settings > Integrations > MCP to see which tools are available.

"Claude Code still says Gravitask needs authentication"

Remove the old OAuth-only entry with claude mcp remove gravitask -s local, then add the API-key configuration above. Run claude mcp get gravitask to confirm Claude sees the header-backed server.

"Codex does not show Gravitask tools"

Check that the URL is https://app.gravitask.com/mcp and that bearer_token_env_var contains an environment variable name such as GRAVITASK_API_KEY. The token value itself belongs in that environment variable.

"Timeout or slow response"

Large workspaces with many projects may take a moment to respond. If the issue persists, check the Gravitask status page.

Next step

Ready to try it in Gravitask?

Create a workspace, then come back to this guide when you are ready to configure the workflow.

Keep reading

Helpful next steps from the Gravitask help centre.

We value your privacy. We use optional analytics cookies to understand traffic and improve Gravitask. You can accept, reject, or manage choices in our Cookie Policy.

Preferences