How to connect Claude Code to Gravitask: a complete MCP setup guide

If you spend your day in Claude Code and your team’s work lives in Gravitask, those two surfaces should not be a copy-paste exercise. The Model Context Protocol (MCP) closes the gap. A single configuration line gives Claude Code structured, authenticated access to your projects, tasks, comments, time entries and wiki, both read and write. From the terminal you can then ask it to triage your sprint, draft a status update, file a follow-up, or untangle a slipped dependency.

This guide walks through the full setup end to end. You will generate an API key, register the Gravitask MCP server with the Claude CLI, verify the connection, and run your first real prompts against live project data. It takes about five minutes and works on any plan, including the free tier.

What you can do once Claude Code is connected to Gravitask

MCP is more than read-only context. The Gravitask server exposes the same primitives the app uses, including list_tasks, create_task, update_task, move_task, add_comment, log_time, get_critical_path and a dozen more, so Claude Code can execute multi-step work against your real backlog. Common workflows people set up on day one:

• Sprint triage. “Group every open task in Q3 Launch by priority and tell me which three are most likely to slip.”
• Stand-up prep. “Summarise everything assigned to me that moved in the last 24 hours.”
• Status reports. “Write a Friday update for the Brand Refresh project, grouped by Done / In Progress / Blocked.”
• Backlog grooming. “Find duplicate tasks across Bugs and Support, propose merges, then create the merged tasks for me to approve.”
• Dependency rewiring. “Task MAL-42 is going to slip by a week. Recompute the critical path and propose new due dates for downstream work.”
• Time tracking from a PR. “Log two hours against MAL-31 with a note linking to PR #482.”

Prerequisites

1. A Gravitask workspace. Create one for free if you don’t have one yet. The MCP server works on every plan.
2. Claude Code installed. Run npm install -g @anthropic-ai/claude-code or follow the official installation guide.
3. Workspace admin access in Gravitask. The API & MCP page is admin-gated. If you’re a member, ask your admin to generate the key.

Step 1. Generate a Gravitask API key

Open Gravitask, click the gear icon in the top-right (or your avatar) and head to Settings → Developer → API & MCP. The page is split into two cards. The MCP Connection block at the top gives you the server URL and a ready-made desktop-client config. The API Keys list sits below it.

Click Generate new key, give it a recognisable name (we use Claude Code) and choose a scope. Read only is the right choice if you want Claude to summarise and report but never mutate. Read & Write lets it create and edit tasks. Full access also covers destructive actions like deleting tasks. Pick the lowest scope that does the job.

Step 2. Add Gravitask as an MCP server in Claude Code

With the key on your clipboard, open a terminal and run the claude mcp add command. The Gravitask server is HTTP-based, so there is no separate process to install and no Node dependency to manage. A single line registers it:

claude mcp add --transport http gravitask https://app.gravitask.net/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with the value from the previous step. The command writes the server config to your local Claude Code settings, and you don’t need to restart anything.

Step 3. Verify the connection

Start an interactive session with claude from any directory. The startup banner lists every MCP server it managed to connect to and how many tools each exposes. You should see gravitask with sixteen tools.

If you don’t see gravitask in the banner, run claude mcp list to confirm it’s registered, then claude mcp test gravitask to surface the underlying connection error. The most common causes are a typo in the bearer token, a revoked key, or your workspace admin disabling MCP under Settings → Integrations.

Step 4. Try your first prompts

Now the fun part. Drop these into a Claude Code session and watch it call the right tools, in order, against your real workspace:

• “List every project I’m a member of and the count of open tasks in each.”
• “In the Mobile App Launch project, find tasks in `In Progress` with no comment in the last 5 days and add a polite nudge comment asking for a status update.”
• “Summarise the last 7 days of completed tasks in the Brand Refresh project. Group by section and write it as a Friday team update.”
• “Create a task in the Bugs project: title ‘Login form rejects @ in passwords’, priority High, assignee me, due Friday.”

Real workflows worth setting up on day one

Morning brief

First prompt of the day: “List everything assigned to me that’s due in the next 48 hours, then anything on a project I own that has changed in the last 16 hours.” Claude Code returns a tight punch list before you’ve opened the Gravitask UI, and you can immediately follow up with “reorder these by criticality and add a one-line plan for each.” The 16-hour window is just a rough overnight cut; pick whatever interval matches your routine.

Pull request to task linking

When you finish a PR, ask Claude Code to find the matching Gravitask task by short ID (it understands GRV-42 style prefixes), move it to In Review, post a comment with the PR link, and log the time you tracked locally. One sentence, four MCP calls, everything stays in sync.

Friday status digest

Pipe the question “Draft a Friday update for the Q3 Launch project: Done, In Progress, Blocked, At risk, with bullets and assignee initials” into Claude Code, and it returns a clean Markdown digest you can paste into Slack or send through the Gravitask wiki. Combine with the Gravitask Workload report for a manager-friendly version.

Sprint planning over the critical path

Before sprint planning, ask “Run getcriticalpath on Q3 Launch and tell me which two tasks, if delayed by a day, would slip the milestone the most.” Claude Code reasons over the dependency graph that Gravitask already maintains, so the answer is grounded in real data rather than a guess.

Troubleshooting

Security notes

• Keys are workspace-scoped. A key generated in one workspace can’t see another, even if the same user is an admin in both. Generate a separate key per workspace.
• Hashed at rest. Gravitask only stores a hashed prefix of each key. Lose it and it’s gone. There is no “show secret” button.
• Rotate regularly. The API & MCP page shows the last-used timestamp for each key. If a key hasn’t been used in months, revoke it.
• Per-tool disable. Admins can disable any MCP tool for the whole workspace, so a “read-only for AI” policy is enforceable from the server side, not just the client.

FAQ

Next steps

Once Claude Code is wired into Gravitask, the obvious next move is to wire the same key into your editor. Cursor, Windsurf and VS Code all use the same configuration shape. After that, look at Gravitask’s native automations for the work that doesn’t need an LLM in the loop, and reserve Claude Code for the planning, writing and judgement calls that do.

If you don’t have a Gravitask workspace yet, start one for free. No credit card, no trial timer, MCP enabled out of the box.