Model Context ProtocolClaude CodeCursorCodexGemini CLIVS Code · Windsurf · Zed

AI-native project management

Connect any MCP-compatible AI agent to Flokzy. The agent plans, tracks and reports work in the same projects and tasks your team uses — and it can’t invent identifiers, statuses or deadlines, because every name is resolved against your workspace before anything is written.

What your AI can do

✓Turn a goal into a project with tasks, sub-tasks, priorities and deadlines
✓Find the task behind a branch or PR and use its description as requirements
✓Record findings and decisions as comments while it works
✓Move tasks through your workflow statuses and close them with a summary
✓Report project progress and draft standups from real task state
✓Refuse to guess: unknown statuses, projects or labels come back as errors listing the valid options

Setup

Create an API key

Open Settings → Developer and create a key. It starts with flkzy_ and is shown once. Unless you narrow it, a new key gets six scopes: tasks:read, tasks:write, projects:read, projects:write, workspace:read and workspace:write — workspace:read covers members, teams, statuses, labels, cycles and search. Deletes and AI usage are opt-in; see Scopes below.

Connect your agent to the hosted server

The hosted server at https://mcp.flokzy.com/mcp speaks MCP over Streamable HTTP. Nothing to install — authenticate with your key as a bearer token.

Claude Code

claude mcp add --transport http flokzy https://mcp.flokzy.com/mcp \
  --header "Authorization: Bearer flkzy_YOUR_KEY"

To share the server with your team, commit a project-scoped .mcp.json that reads each person’s key from their environment — Claude Code expands ${FLOKZY_API_KEY} when it loads the file:

{
  "mcpServers": {
    "flokzy": {
      "type": "http",
      "url": "https://mcp.flokzy.com/mcp",
      "headers": { "Authorization": "Bearer ${FLOKZY_API_KEY}" }
    }
  }
}

Writing it with --scope project instead? Put the header in single quotes ('Authorization: Bearer ${FLOKZY_API_KEY}'): in double quotes your shell expands the variable and writes your real key into the committed file.

Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "flokzy": {
      "url": "https://mcp.flokzy.com/mcp",
      "headers": { "Authorization": "Bearer flkzy_YOUR_KEY" }
    }
  }
}

Keep a literal key out of files you commit.

OpenAI Codex — ~/.codex/config.toml

[mcp_servers.flokzy]
url = "https://mcp.flokzy.com/mcp"
bearer_token_env_var = "FLOKZY_API_KEY"

Export FLOKZY_API_KEY in your shell; Codex sends it as the bearer token.

Gemini CLI

gemini mcp add --scope user --transport http \
  --header "Authorization: Bearer flkzy_YOUR_KEY" flokzy https://mcp.flokzy.com/mcp

--scope user writes ~/.gemini/settings.json; without it the key lands in the project’s .gemini/settings.json.

VS Code (Copilot agent mode) — .vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "flokzyApiKey", "description": "Flokzy API key (flkzy_…)", "password": true }
  ],
  "servers": {
    "flokzy": {
      "type": "http",
      "url": "https://mcp.flokzy.com/mcp",
      "headers": { "Authorization": "Bearer ${input:flokzyApiKey}" }
    }
  }
}

VS Code asks for the key once and stores it outside the file, so the file is safe to commit.

Windsurf, Zed, Claude Desktop and other clients

Any client that can launch a local command can run the package over stdio (see below) or reach the hosted server through mcp-remote. Put the header value in an environment variable rather than one Authorization: Bearer … argument: some clients split arguments on spaces.

{
  "mcpServers": {
    "flokzy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.flokzy.com/mcp", "--header", "Authorization:${FLOKZY_AUTH_HEADER}"],
      "env": { "FLOKZY_AUTH_HEADER": "Bearer flkzy_YOUR_KEY" }
    }
  }
}

Claude Desktop needs this bridge: its remote connectors do not take custom headers. In Zed, add a custom context server with the same command, arguments and environment.

Every request to the hosted server needs the same Authorization: Bearer flkzy_… (or X-Flokzy-Api-Key) header — the server binds each session to the key that opened it, so restart your client after rotating or swapping keys.

Verify

In Claude Code run /mcp (or claude mcp list) and check that flokzy is connected. In Cursor the MCP panel shows a green dot. Then ask your agent: “List my open Flokzy tasks.”

Scopes

A key carries an explicit list of scopes, chosen when you create it under Settings → Developer. A new key gets six of the nine by default; deletes (tasks:delete, projects:delete) and ai:use are opt-in — enable them individually when creating or editing a key. tools/list only returns the tools your key’s scopes unlock, so an agent never sees a write it would be refused; call one anyway (a name it remembers from another workspace) and the result is a tool error naming the missing scope.

Scope	Default	Unlocks
tasks:read	On	Read tasks, comments, links, activity
tasks:write	On	Create and update tasks, comments, links
tasks:delete	Opt-in	Permanently delete tasks, comments, attachments
projects:read	On	Read projects and burndown
projects:write	On	Create, update, archive projects
projects:delete	Opt-in	Permanently delete projects
workspace:read	On	Members, teams, statuses, labels, cycles, views, analytics
workspace:write	On	Create and edit labels, cycles, teams, statuses, views
ai:use	Opt-in	Run AI summaries and triage (spends the workspace AI budget)

Run the server locally instead

Prefer a local process, or want the agent to notice the task in your current git branch? Run the package over stdio. It reads FLOKZY_API_KEY from the environment and, with FLOKZY_AUTO_BRANCH=true, tells the agent about the task referenced by branches such as feat/ENG-42-login.

{
  "mcpServers": {
    "flokzy": {
      "command": "npx",
      "args": ["-y", "@flokzy/mcp"],
      "env": {
        "FLOKZY_API_KEY": "flkzy_YOUR_KEY",
        "FLOKZY_AUTO_BRANCH": "true"
      }
    }
  }
}

Claude Code: claude mcp add flokzy --env FLOKZY_API_KEY=flkzy_YOUR_KEY -- npx -y @flokzy/mcp. Self-hosting the HTTP server: npx -p @flokzy/mcp flokzy-mcp-http serves /mcp on PORT (default 3001). It binds to 127.0.0.1 by default — put a TLS proxy in front, or set MCP_HOST=0.0.0.0 in a container — and accepts up to MCP_MAX_SESSIONS live sessions (default 500) before answering 503.

Teach your agent the workflow

The server already tells every agent how to behave (look up before writing, never invent identifiers or deadlines, record decisions as comments, close tasks only when the work is verified). For agents that support the open Agent Skills format, install the companion skill so the agent reaches for Flokzy whenever work is planned, tracked or reported:

# Claude Code (project) — Codex uses .agents/skills/ instead
mkdir -p .claude/skills/flokzy-project-management
curl -fsSL https://flokzy.com/skills/flokzy-project-management/SKILL.md \
  -o .claude/skills/flokzy-project-management/SKILL.md

Or download SKILL.md directly and place it yourself. For Cursor or Gemini CLI, paste the same file into your rules (.cursor/rules, GEMINI.md).

Available tools

38 tools. Every tool accepts human names — task identifiers like ENG-42, status names, project names, label names — and resolves them for the agent. Read-only tools are marked read for clients that ask for confirmation before writes; delete tools only appear for a key that carries the noted scope.

Tasks

Tool	Kind	Description
list_tasks	read	Filter by text, assignee, status, priority, project, cycle, parent, labels, due window, scope
get_task	read	Full task detail; add comments, sub-tasks or linked GitHub PR state with include
search	read	Full-text search across tasks, projects, cycles and labels
create_task	write	Title, Markdown description, priority, status, assignee, project, dates, estimate, parent, labels, cycle
update_task	write	Change any field; archived hides it, null clears a value
close_task	write	Complete a task, optionally with a closing comment
bulk_update_tasks	write	The same change on up to 100 tasks in one call — confirm first
get_task_activity	read	Change history: what changed, who changed it, and from where
set_task_watch	write	Subscribe this account to a task’s notifications, or unsubscribe it
task_stats	read	Counters for this account: assigned open, in progress, overdue
list_templates	read	Task templates: title prefix, description skeleton, default priority, labels
create_task_from_template	write	Create a task from a saved template, appending your title and description
delete_task	delete · needs `tasks:delete`	Permanently delete a task with its comments, links and history — prefer archiving

Comments, links & GitHub

Tool	Kind	Description
add_comment	write	Record findings, decisions and links on a task
list_comments	read	Read a task’s discussion, in chronological order
delete_comment	delete · needs `tasks:delete`	Permanently remove one comment from a task
link_tasks	write	Record blocks / related / duplicates relationships
list_links	read	The relations a task has, with each other task’s identifier, title and status
unlink_tasks	write	Remove the relation(s) between two tasks, optionally narrowed by kind
get_github_context	read	PR or issue state, reviews and checks for a linked task

Projects

Tool	Kind	Description
list_projects	read	Projects (goals) with status, target date, lead and progress
get_project	read	One project with its description and open tasks
create_project	write	Create a project with a goal description, status and target date
update_project	write	Change project status, deadline, lead, description
get_burndown	read	Remaining work against the ideal line and a trend, for one project or one cycle
delete_project	delete · needs `projects:delete`	Permanently delete a project; its tasks survive, detached — prefer archiving

Workspace

Tool	Kind	Description
whoami	read	The account this connection acts as, its organization, and the scopes the key carries
list_members	read	People in the workspace so work can be assigned by name
list_teams	read	Teams and their workflow statuses (needed to set status by name)
list_labels	read	Available labels and their groups
list_cycles	read	Cycles (sprints) with dates, state and progress
create_label	write	Add a label: name, hex colour, optional team and group
update_label	write	Rename a label, recolour it, or move it in or out of a group
create_cycle	write	Create a sprint with a start and an end date
update_cycle	write	Rename a cycle, shift its dates, or close it
create_status	write	Add a workflow status (board column) to a team, in a category
update_status	write	Rename, recolour or recategorise a team’s status
create_team	write	A new team with its own key, board and default status set

Built-in prompts

plan_work

Turns a goal (and optional deadline) into a project with tasks, sub-tasks and dependencies — after checking what already exists. It drafts the breakdown first and asks you to confirm before creating more than three tasks, each with a type label and a priority.

pr_context

Given a branch name, PR title or URL containing a task identifier, loads the task, its comments and PR state as requirements context.

daily_standup

Fetches your open tasks and drafts a Yesterday / Today / Blockers update from them.

Troubleshooting

401 Unauthorized: The key is missing, revoked or mistyped. It must start with flkzy_ and be sent as Authorization: Bearer … (or X-Flokzy-Api-Key). Create a new key under Settings → Developer.
403 on a tool call: Your key doesn’t carry the scope that tool needs — the error names it, e.g. “Create a key that includes the ‘projects:write’ scope under Settings → Developer.” Keys created before 2026-09-05 predate the workspace scopes and can’t resolve people, statuses, labels or cycles by name; create a new key (six default scopes) or add scopes when creating one.
“Unknown status / project / label” errors: Working as intended: the agent used a name that doesn’t exist in your workspace. The error lists the valid options; the agent should pick one or ask you rather than guess.
Tools not appearing: Restart the client after editing its config. Claude Code shows connection errors in /mcp; Cursor in the MCP panel. A tool missing from the list usually means your key lacks the scope it needs (see Scopes);whoami always works and reports the scopes your key carries. The hosted server answers GET https://mcp.flokzy.com/healthz when it is up.

Get API key →@flokzy/mcp on npm →MCP specification →