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
- 1A Gravitask account. Create one for free.
- 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.
| Situation | Use |
|---|---|
| Claude.ai, Claude Desktop, ChatGPT | OAuth |
| Claude Code, Cursor, VS Code, other CLIs and IDEs | API key |
| A bot or script with one job (for example logging time) | API key with tool groups |
| Analysis and reporting only | Either, 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
| Tool | Permission |
|---|---|
gravitask_list_projectsList projects in the workspace with task/member counts. | Read |
gravitask_get_projectGet one project with its members, sections (status columns), and task count. | Read |
gravitask_list_tasksList 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_taskGet one task in full: description (as markdown), subtasks, comments, tags, attachments, custom fields, time entries. | Read |
gravitask_create_task_previewDry-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_commentsList comments on a task (oldest first) with author and markdown content. | Read |
gravitask_searchRanked full-text search across tasks, projects, comments, and wiki pages in the workspace (typo-tolerant, matches descriptions too). | Read |
gravitask_get_workspaceGet the connected workspace: name, project count, and members with roles. | Read |
gravitask_list_membersList workspace members (id, name, email, role), the source of valid assignee_id / user_id values. | Read |
gravitask_list_tagsList the tags of one project (tags are project-scoped). | Read |
gravitask_list_dependenciesList 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_milestonesList a project's milestones (id, name, date, completed) ordered by date. | Read |
gravitask_list_sectionsList 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_tasksAnswer "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_activityA 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_fieldsList 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_attachmentsList a task's attachments (file name, URL, size, source, uploads, cloud files, and links). | Read |
gravitask_list_collaboratorsList the people following a task besides the assignee (reviewers/watchers who get notified of changes). | Read |
gravitask_list_notificationsThe 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_recurrenceInspect 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_portfoliosList the workspace's portfolios with their member projects, the roll-up grouping for exec-level questions. | Read |
gravitask_list_goalsList 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_goalOne goal with its task-completion roll-up computed across the linked projects (total/completed per project and overall progress percent). | Read |
gravitask_list_formsList a project's intake forms (name, public slug, active state, submission count). | Read |
gravitask_list_lookup_tablesList the workspace's lookup tables (reference data used by automations): columns, key column, and row counts. | Read |
gravitask_get_lookup_tableRead a lookup table's rows (as key→value records) with cursor pagination, the reference data automations resolve against. | Read |
gravitask_get_critical_pathCompute the critical path of a project from task dependencies: the chain of tasks driving the end date, plus per-task float. | Read |
Create & update
| Tool | Permission |
|---|---|
gravitask_create_taskCreate a task in a project. | Write |
gravitask_plan_taskWorkflow 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_tasksBatch 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_tasksBatch update up to 50 tasks in one call, bulk re-prioritise, re-assign, or re-schedule without N round-trips. | Write |
gravitask_complete_tasksBatch close up to 50 tasks in one call (sets status DONE, fires the same automations as closing in the app). | Write |
gravitask_update_taskUpdate task fields (title, markdown description, status, priority, assignee, dates, section). | Write |
gravitask_complete_taskClose a task (sets status DONE and stamps completedAt). | Write |
gravitask_move_taskMove a task to another project and/or change its status. | Write |
gravitask_add_commentAdd a comment to a task. | Write |
gravitask_create_tagCreate a tag in a project (upsert, an existing tag with the same name is returned, not duplicated). | Write |
gravitask_add_tag_to_taskAttach a tag to a task by tag_id or tag_name (looked up in the task's project). | Write |
gravitask_remove_tag_from_taskDetach a tag from a task by tag_id. | Write |
gravitask_create_dependencyMake one task depend on another task OR on a milestone (exactly one of depends_on_task_id / depends_on_milestone_id). | Write |
gravitask_delete_dependencyRemove a dependency edge by its UUID (get it from list_dependencies). | Write |
gravitask_create_milestoneCreate a dated milestone in a project, the anchor points that dependencies and the critical path compute against. | Write |
gravitask_update_milestoneUpdate a milestone's name, date, description, color, or completed flag. | Write |
gravitask_create_sectionAdd a section (board column) to a project, appended after the existing columns. | Write |
gravitask_update_sectionRename or recolor a section, or reorder it by anchoring after_section_id / before_section_id (sections in the same project). | Write |
gravitask_set_custom_fieldSet 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_linkAttach 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_collaboratorAdd a workspace member as a collaborator (watcher) on a task, they are notified like in the app. | Write |
gravitask_remove_collaboratorRemove a collaborator from a task. | Write |
gravitask_mark_notification_readMark one of the connected user's notifications as read after triaging it. | Write |
gravitask_set_recurrence_pausedPause or resume future occurrence generation for a task's recurring series. | Write |
Wiki
| Tool | Permission |
|---|---|
gravitask_list_wiki_pagesList wiki pages in the workspace as lean summaries (id, shortId, title, state, scope, updatedAt). | Read |
gravitask_search_wiki_pagesFull-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_pageRead one wiki page in full (title, plain-text body, owner, verification state) by its UUID. | Read |
gravitask_create_wiki_pageCreate a wiki page from plain text. | Write |
gravitask_update_wiki_pageUpdate a wiki page title, plain-text body, or owner. | Write |
gravitask_verify_wiki_pageMark a wiki page as verified (optionally until expires_at, ISO 8601), signalling the content is accurate. | Write |
Time tracking
| Tool | Permission |
|---|---|
gravitask_list_time_entriesList time entries filtered by task, project, user, or ISO date range, the building block for timesheet and utilisation questions. | Read |
gravitask_log_timeLog manual time against a task in minutes, optionally billable and dated (defaults to today). | Write |
gravitask_time_summaryAggregate logged time by project, user, or day over an optional date range, answers "how much time did we log". | Read |
Automations
| Tool | Permission |
|---|---|
gravitask_list_automationsList the workspace's automation rules (id, name, enabled, scope, trigger type, run stats). | Read |
gravitask_get_automationGet one automation rule in detail: trigger, conditions, step count, run stats, and the 5 most recent runs with status and errors. | Read |
gravitask_run_automationFire 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_automationSurface AI-generated automation rule suggestions for a project. | Write |
Reporting
| Tool | Permission |
|---|---|
gravitask_workload_by_assigneeOpen and overdue task counts per assignee across the workspace (or one project), answers "who is overloaded" for rebalancing decisions. | Read |
gravitask_project_progressOn-track signal for one project: total / completed / overdue task counts, completion rate percent, and a per-status breakdown. | Read |
Admin
| Tool | Permission |
|---|---|
gravitask_delete_taskPERMANENTLY 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
Related support guides
Helpful next steps from the Gravitask help centre.
AI integration
Connect Claude to Gravitask
Add Gravitask as a custom connector in Claude on the web or desktop with one-click OAuth.
Read guideAI integration
Connect ChatGPT to Gravitask
Add Gravitask as a custom MCP connector in ChatGPT developer mode with OAuth sign-in.
Read guideDeveloper API
REST API Documentation
Build integrations with projects, tasks, comments, time entries, and webhooks.
Read guide