@flnkit/mcp-server

Model Context Protocol server for the FastLinkIt Projects API. Plug it into Claude Desktop, Cursor, Continue, or any other MCP-aware client and drive your project board with natural language — without leaving the editor.

What is this? A Node.js MCP server that exposes the FastLinkIt Projects REST API as a set of typed tools. Your MCP client calls the tools when you describe what you want; the project board updates in real time. Same operations as the Claude Code project-planner skill, exposed for clients that aren't Claude Code.

What you can do

| You say | What lands on the board | |---|---| | "What's next for the Agile project?" | A ranked, methodology-aware plan (Epic → Feature → Story → Task hierarchy) — the client waits for your "yes", then creates the items in one round-trip. | | "I'll start on FLNKA-22" | Item moves to In progress. Assignee is set to "Claude Code". Agent-run row records the pickup. | | "Done — added the migration, tests pass" | Item moves to Review with your narrative summary attached. | | "Bug: the resize handle loses pointer events after a re-render" + paste a screenshot | Bug created with structured repro steps, the screenshot attached as evidence. | | "What's on my plate?" | Items assigned to you, grouped by status (In progress / Backlog / Review). Suggests resume / pickup. |

Five modes total: Plan, Pickup, Wrap-up, Bug, Scan. All gated by an explicit human "yes" before anything writes to the board — no auto-push.

What is FastLinkIt?

flnk.it is a small-business / creator / freelancer toolkit that bundles features you'd otherwise stitch together from Bitly + Linktree + Calendly + Mailchimp + Stripe + Zendesk + WordPress, into a single platform with one bill, one REST API, and a coherent UI.

The Projects module is the part this MCP server drives — Kanban / Agile / Waterfall over a unified work-item model with PERT estimation, sprints, Gantt, time tracking, AI agents.

A few of the things flnk.it does:

• Link shortener, QR codes, link-in-bio pages
• Contact CRM + email mailings with drip campaigns + A/B testing + DKIM-signed sender domains
• Event booking, payments + donations, service requests
• REST API, CMS plugins (WordPress, Joomla, Drupal, Ghost, Shopify, Wix)
• Projects (this one)

Don't have an account yet?

You'll need one — that's where the projects live. Create one for free →

• Free plan, no card required.
• 14-day free trial on every paid plan (Starter / Basic don't need a card to start the trial).
• Pricing: flnk.it/pricing.

The seven MCP tools

| Tool | Purpose | |---|---| | list_projects | List the user's projects (id, name, methodology, item count). | | get_project_context | Fetch one project's methodology, allowed work-item types, Kanban columns, recent items. Optional assignee arg filters items to a specific user / agent (used by Scan mode). | | submit_plan | Materialise a plan as work items. Hierarchy (parent_local_id) and FinishToStart dependencies (depends_on_local_ids) round-trip cleanly. | | start_task | Open an agent run on a work item. Moves it to the in-progress column, sets assignee to the agent identifier when previously empty, returns a runId. | | complete_task | Close run successfully. Moves to review (or done with skipReview: true). Carries a markdown narrative shown in the work item's preview. | | block_task | Close run as Blocked. Reason is mandatory. | | attach_to_work_item | Upload a file (screenshot, log dump, repro recording) as a work-item attachment. Allowlisted by extension. Max 25 MB. |

End-to-end walkthrough — from zero to your first AI-driven plan

Assume you've never used the Projects module before. Every step is concrete; replace project names with your own.

Step 1 — Create a project in the FastLinkIt UI

Sign in at flnk.it, click Projects in the left rail → + New project. Fill in:

• Name: "Acme website rebuild"
• Methodology: Agile (full Epic / Feature / Story / Task hierarchy). Pick Kanban for a flat task pool, or Waterfall for date-driven Gantt work.
• Prefix: WEB (so items number as WEB-1, WEB-2, … instead of bare #1).
• Status: Active. Colour: pick one. Hourly rate: optional, only matters if you'll bill time.

Save. You land on /projects/{id} with an empty list view. Note the project id in the URL bar — you'll paste it into PROJECTS.md in step 2.

Step 2 — Tell the client about the project (PROJECTS.md)

When your MCP client (Cursor, Claude Desktop, etc.) reads files from your repo, it'll use a PROJECTS.md to resolve aliases, pick the default project, and shape proposals. The same template works whether you're using the Claude Code skill or this MCP server.

a) Copy the starter template into your repo.

The starter lives at PROJECTS.template.md in the sibling skill folder. Download or copy it to your repo's root as PROJECTS.md.

b) Find each value in the UI and replace the bracketed placeholder.

The template has placeholders like <project-name-1>, <PFX1>, <guid>. Here's where each one comes from:

| Template placeholder | Where to find it in the UI | |---|---| | <project-name-1> | The Name you typed when creating the project. | | <PFX1> (prefix) | The Prefix field on /projects/{id}/edit. Same letters that appear before the dash on every work-item number — WEB-1, WEB-2. Use — if you didn't set one. | | <methodology> | The methodology pill on /projects/{id} (Agile / Kanban / Waterfall). | | <guid> (project id) | The Guid in the URL bar: /projects/78995612-0360-4530-8fec-30443c0a61da — that whole second segment is the id. | | <one-line purpose> | A short note describing the project — "main delivery board", "bug-tracker for the WordPress plugin". | | Aliases | Whatever shorthand you'll naturally say in conversation. The prefix (WEB) is always good; "the website", "frontend" — anything you'd say out loud. | | Default project | One of the names from your table — the one you'll mean when you just say "what's next?" with no scope. |

c) Minimum viable PROJECTS.md for the Acme example:

## Projects

| Project name | Prefix | Methodology | id | Notes |
|---|---|---|---|---|
| Acme website rebuild | WEB | Agile | 78995612-0360-4530-8fec-30443c0a61da | Default project. |

## Project aliases

| Alias | Project |
|---|---|
| `acme`, `the website`, `WEB` | **Acme website rebuild** |

**Default project** (when the user gives no project hint): **Acme website rebuild**.

(Replace the example Guid with your actual project id from the URL.)

That alone unblocks "what's next for acme?" without the disambiguation prompt.

d) Commit PROJECTS.md to your repo so the planning context ships with the codebase.

Note for MCP clients — unlike Claude Code (which auto-loads the skill folder), MCP clients vary in how they treat project files. Cursor reads PROJECTS.md if it's in the workspace root. Claude Desktop has no concept of repo context — point it at the file via system prompt or just paste-quote when asking project questions. The MCP server itself doesn't read PROJECTS.md; it only exposes the tools the client uses.

Step 3 — Generate an API key

Browser → /Account/Manage/ApiKeys → Generate new key → name it "Claude Desktop on my laptop" → tick the projects scope → Create → copy the raw fli_... key. The key is shown once.

Step 4 — Install the MCP server

Option A — npm (recommended):

npm install -g @flnkit/mcp-server

The binary lands at flnkit-mcp-server on your PATH.

Option B — build from source:

# Clone the source — see the npm package's `repository` field for the
# canonical repo URL.
npm view @flnkit/mcp-server repository
# Then clone whatever URL it points at, cd into the project, and:
npm install
npm run build

The runnable binary is at dist/index.js. You'll point your MCP client's command at that path instead of flnkit-mcp-server.

Step 5 — Wire it into your MCP client

The MCP server reads four env vars. Set them inside the client's mcpServers config (NOT in your shell — most MCP clients ignore the shell environment):

| Var | Default | Notes | |---|---|---| | FLNKIT_API_KEY | — required — | The fli_... key from step 3. | | FLNKIT_API_BASE | https://flnk.it | Override for self-hosted (e.g. https://fastlinkit.dev.localhost:7152 for local dev). | | FLNKIT_AGENT_ID | claude-code | Free-form identifier stamped on every agent-run row. Set to cursor, claude-desktop, etc. so you can distinguish which client did what. | | FLNKIT_INSECURE | 0 | Set to 1 (or use a localhost base URL) to skip TLS verification. |

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "flnkit-projects": {
      "command": "flnkit-mcp-server",
      "env": {
        "FLNKIT_API_KEY": "fli_your_key_here",
        "FLNKIT_API_BASE": "https://flnk.it",
        "FLNKIT_AGENT_ID": "claude-desktop"
      }
    }
  }
}

If you installed via git-clone instead of npm, point command at the absolute path to dist/index.js:

{
  "command": "node",
  "args": ["/abs/path/to/FastLinkIt/Plugins/mcp-server/dist/index.js"],
  "env": { "FLNKIT_API_KEY": "fli_...", "FLNKIT_AGENT_ID": "claude-desktop" }
}

Restart Claude Desktop. The flnkit-projects server appears in the status bar with seven tools available.

Cursor

Cursor reads MCP config from ~/.cursor/mcp.json:

{
  "mcpServers": {
    "flnkit-projects": {
      "command": "flnkit-mcp-server",
      "env": {
        "FLNKIT_API_KEY": "fli_...",
        "FLNKIT_AGENT_ID": "cursor"
      }
    }
  }
}

Continue / Other MCP clients

Continue and most other MCP-aware clients use the same mcpServers shape. Consult your client's MCP integration docs for the exact path.

Step 6 — Smoke-test

In your MCP client, ask:

"What FastLinkIt projects do I have access to?"

The client calls list_projects via the MCP tool and reports your projects. If you see the project name from step 1, you're wired up correctly.

You can also use the MCP Inspector to test the server outside any client:

FLNKIT_API_KEY=fli_... npx @modelcontextprotocol/inspector flnkit-mcp-server

Step 7 — Plan your first batch of work

"What's next for acme? I want to focus on the homepage redesign."

The client reads PROJECTS.md (when supported), calls get_project_context, then proposes a structured plan:

I propose for Acme website rebuild:

1. EPIC      Homepage redesign                          (no estimate)
2.   FEATURE     Hero + above-the-fold rework            (likely: 14h)
3.     STORY     As a visitor I want a clearer value prop above the fold   (likely: 6h)
4.     STORY     As a visitor I want a faster LCP score under 2.5s         (likely: 8h)
5.   FEATURE     Social proof section                                       (likely: 8h)
6.     STORY     As a marketer I want to show 3 customer logos and 2 quotes (likely: 5h)
7.     TASK      Wire the quote carousel to the CMS                         (likely: 3h)

Push these to Acme website rebuild? (y / N)

Reply "y". Items land on the board as WEB-1 through WEB-7.

Step 8 — Pick up your first item

"I'll start on WEB-3 — the value-prop refresh"

The client calls start_task. WEB-3 moves to In progress, the assignee column shows "Claude Desktop" (or whatever FLNKIT_AGENT_ID you set), and the agent-run history records the pickup.

Step 9 — Wrap up

"Done — replaced the hero copy, ran the LCP profile in Chrome DevTools (2.1s now), pushed to main"

The client calls complete_task with the narrative. WEB-3 moves to Review with your summary attached.

Step 10 — What next?

• "What's on my plate?" — Scan mode: items assigned to you, grouped by status.
• "Bug: " + paste a screenshot — Bug mode: structured bug with attachment.
• "Plan three more stories for the social proof feature" — Plan mode with auto-parenting under the existing feature.
• "How's acme tracking?" — progress check.

The five modes in detail

Plan mode

Triggers: "What's next for X?", "plan some work for X", "give me a plan for the homepage redesign".

Behaviour: client calls list_projects → identifies the project (using your aliases from PROJECTS.md) → calls get_project_context for methodology + columns + recent items → proposes a methodology-aware plan:

| Methodology | Default plan shape | |---|---| | Agile | Hierarchy: one Epic → 2-5 Features → Stories → Tasks/Subtasks. Tiny goals (one cohesive change) skip the epic and produce 1-3 stories directly. | | Waterfall | Phase-shaped task chain: ordered tasks with depends_on_local_ids so FinishToStart edges drive the Gantt + critical-path scheduler. | | Kanban | Flat list of task / bug rows. No artificial hierarchy. |

Override the shape mid-flight: "don't bother with an epic, just stories", "group these into two epics", "these can run in parallel — no dependencies". The client reshapes and re-prints.

Always confirms before pushing. "Looks good" / "let's see" are NOT consent — only an explicit "y" / "yes" / "ship it".

Pickup mode

Triggers: "I'll start on WEB-N", "pick up the next one", "resume FLNKA-22".

Behaviour: Calls start_task against the work item. Server moves the item to the in-progress column, sets assignee to the agent identifier (only when previously empty — won't trample a human assignee), and returns a runId the client stores for the wrap-up call.

If you say "pick up the next one" without naming an item, the client finds the highest-priority backlog item assigned to the agent (via get_project_context with assignee=<your-agent-id>) and proposes it before calling start_task.

Wrap-up mode

Triggers: "done", "I'm done with WEB-3", agent finishes a natural unit of work and announces completion.

Success path: Calls complete_task with a narrative summarising what changed (key files, follow-up items spawned, gotchas). Item moves to Review (or Done if you say "skip review").

Stuck path: "Stuck — need a design call before I can finish" → calls block_task with the reason. Item moves to Blocked with the reason logged. The reason is mandatory — no silent failures.

Bug mode

Triggers: "log a bug", "bug:", "I just hit X", "this looks broken".

Behaviour: Drafts a single bug item with a structured repro template:

Repro steps:
1. <step 1>
2. <step 2>
…

Expected: <what should happen>
Actual:   <what happens instead>

Affected: <page / component / file path>
Environment: <browser / OS — when relevant>

Defaults: priority=normal (escalates to high on "blocking" / "broken in prod" phrasing), tags=["bug", <area>], no parent. Auto-parents to the parent feature when the bug surfaces mid-pickup.

Attachments: paste a screenshot in the same message and the client lists it in the proposal preview (📎 Attachments: filename.png (442 KB)). On confirmation the bug is created via submit_plan, then each attachment uploads via attach_to_work_item. Allowed: images / PDFs / docs / archives / video. Rejected: executables. Max 25 MB per file.

Scan mode

Triggers: "What's on my plate?", "anything assigned to me?", "pick up the next one", "what should I resume?".

Behaviour: Calls get_project_context with the assignee filter set to the agent identifier (claude-code by default — set FLNKIT_AGENT_ID to your client name for clearer audit). Returns items grouped by status:

You have 4 items assigned to claude-desktop on Acme website rebuild:

In progress (1)
- WEB-3  As a visitor I want a clearer value prop above the fold
        ⚠ run from previous session may still be open

Backlog (2)
- WEB-4  As a visitor I want a faster LCP score under 2.5s    priority: high
- WEB-7  Wire the quote carousel to the CMS                   priority: normal

Review (1)
- WEB-3  …                                                    (waiting for human review)

Want me to resume WEB-3, or pick up WEB-4 next? (or "neither")

Never auto-resumes. Always asks before calling start_task.

Local development

# Clone the source repo — find it via:
npm view @flnkit/mcp-server repository
# Then:
npm install
npm run watch          # tsc --watch

In another shell, smoke-test against a local FastLinkIt dev instance:

FLNKIT_API_KEY=fli_... \
FLNKIT_API_BASE=https://fastlinkit.dev.localhost:7152 \
node dist/index.js

The server speaks MCP over stdio — there's no port to point a browser at. Test it via MCP Inspector:

FLNKIT_API_KEY=fli_... \
FLNKIT_API_BASE=https://fastlinkit.dev.localhost:7152 \
npx @modelcontextprotocol/inspector node dist/index.js

Cross-client alternative — Claude Code skill

If you're a Claude Code user, the project-planner skill is a better fit. It auto-loads from ~/.claude/skills/ so Claude Code reads the playbook on every session without requiring an MCP client config block. Same operations, same five modes, same PROJECTS.md contract — just a different distribution channel.

| | Claude Code skill | MCP server (this) | |---|---|---| | Works in | Claude Code only | Claude Desktop, Cursor, Continue, any MCP-aware client | | Install | git-clone — copy folder into ~/.claude/skills/project-planner/ | npm install -g @flnkit/mcp-server | | Per-call shape | Helper script + args | Native MCP tool calls | | Best when | You live in Claude Code | You bounce between editors / use multiple clients |

Troubleshooting

FLNKIT_API_KEY env var is required

The env var didn't make it to the server process. Most common cause: you set it in your shell but the MCP client launched the server fresh, ignoring shell env. Edit your client's MCP config and put the env vars inside the env: { … } block under your server entry. Restart the client.

Server appears in client status as "failed" or doesn't show up

Check the client's MCP server logs:

• Claude Desktop: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\mcp*.log (Windows).
• Cursor: View → Output → "MCP" in the bottom panel dropdown.

Common errors: command not found (npm bin not on PATH — use absolute path), missing API key (see above), self-signed cert error (set FLNKIT_INSECURE=1).

403 Forbidden on every call

API key doesn't have the projects scope. Generate a new one with the scope ticked.

409 Another agent run is already active

You opened a run on this item before and didn't close it. Two options:

1. Resume: ask the client "complete the open run on WEB-3 with a narrative of what got done".
2. Wait it out: the server expires stale runs after 10 minutes of inactivity.

400 Some items use a work-item type that's not allowed for this Kanban project

The client tried to push a story to a Kanban project (which only allows task / bug). Re-prompt: "that's a Kanban project — convert the stories to tasks and resubmit".

Self-signed cert errors on a dev host

If hitting https://fastlinkit.dev.localhost:7152: the MCP server auto-detects localhost and disables TLS verification. If it doesn't catch it, set FLNKIT_INSECURE=1 in your client's MCP env block.

What this server does NOT do

By design:

• It will never push without your explicit "yes". "Looks good" / silence are not consent.
• It won't pick the project for you when multiple match. It'll list the candidates and ask.
• It won't modify or delete existing items — only creates new items and transitions status. For edits / merges / splits / re-parenting, use the web UI.
• It won't auto-merge code changes. Code execution is a separate scoping (Phase 1c on the AI roadmap).
• It won't bypass plan-based access controls. The same scope and ownership checks that gate the web UI gate the API.

Privacy

Every request carries the API key as X-Api-Key. Nothing is logged beyond the existing FastLinkIt request log. Each tool call writes a WorkItemAgentRun row with AgentId = "claude-code" (or whatever FLNKIT_AGENT_ID overrides to) so you can audit which client triggered which transition. Token / cost columns are 0 for external runs since the model isn't running on the FastLinkIt server.

Attachments go through the existing FastLinkIt attachment path — same storage, same retention, same access controls as files attached via the UI.

Files in this repo

package.json          npm package metadata + scripts
tsconfig.json         TypeScript config
src/
  index.ts            MCP server entry point (stdio transport)
  api.ts              FastLinkIt REST API client
  tools.ts            MCP tool definitions (the seven tools)
README.md             this file

Built output lands in dist/ — only ships in npm publishes, not committed to git.

License

MIT.