-
Notifications
You must be signed in to change notification settings - Fork 0
FAQ
Questions that come up enough to deserve a permanent answer.
For "my host doesn't see the tools" and other configuration / runtime issues, see Troubleshooting.
Anything that speaks the Model Context Protocol over stdio. Tested:
- Claude Desktop (macOS + Windows)
- Cursor
- Zed
- Cline (the VS Code extension)
- Continue
Anything else with command + args + env config support should work — drop the same npx -y @floopfloop/mcp invocation into the host's MCP config block. The README has copy-paste config for Claude Desktop and Cursor; the generic stdio snippet covers the rest.
Three paths, all equivalent:
- Dashboard — Account → API Keys → "Create new". Business plan required to mint new keys.
-
CLI —
floop keys create mcp-host(returns the raw key once; copy it immediately). -
Programmatic —
POST /api/v1/api-keyswith another existing key (cookbook recipe 5 in any SDK).
Stash the resulting flp_… value in the env.FLOOP_API_KEY field of your host's MCP config. Don't share it; treat it like a password.
Both call the same /api/v1/* surface, but they're for different audiences:
@floopfloop/mcp |
floop CLI |
|
|---|---|---|
| Audience | LLM (Claude / Cursor / etc.) running on the user's behalf | Human at a terminal |
| Transport | MCP stdio JSON-RPC | argparse + stdout |
| Auth |
FLOOP_API_KEY env var |
OAuth-style device flow (or FLOOP_API_KEY for CI) |
| Tools | 22 MCP tools | dozens of subcommands + a chat REPL |
| Use it when | You want Claude to manage projects on your behalf | You want to script FloopFloop in CI or a terminal |
If you find yourself wanting both, that's normal — the MCP for Claude orchestrating builds, the CLI for you running quick admin tasks.
Three causes, in decreasing order of likelihood:
-
FLOOP_API_KEYis missing or wrong. The server starts but every tool call fails withUNAUTHORIZED, and some hosts hide tools they can't successfully list. Check the host's MCP log; it should show the spawn command and stderr from the server. - Host hasn't restarted. Claude Desktop / Cursor cache the tool list at server-startup time. Restart the host (not just reload the chat).
-
npxis on a stale package.npx -y @floopfloop/mcpshould pull the latest, but sometimes a corporate proxy caches an older version.npx -y @floopfloop/mcp@latestforces a re-resolve.
Troubleshooting has detailed per-host debugging.
MCP's stdio transport uses JSON-RPC 2.0, which doesn't have a binary frame type. Sending a 5 MB image inline as base64 inside a JSON message bloats it by ~33% and exceeds many hosts' message-size limits.
upload_from_path sidesteps the issue: the LLM tells the MCP server "upload this local file path", the server reads the file off the host's disk, presigns a POST /api/v1/uploads, PUTs the bytes to S3, and returns a normal JSON attachment reference. The image never travels over stdio.
Side effect: the LLM can only attach files that already exist on the user's local filesystem. If you want to attach a file Claude generated in-conversation, you'll need to write it to disk first (e.g. via the Filesystem MCP server) and then call upload_from_path on the path.
Not yet via env var. The current options:
-
Use a single-purpose API key. Mint a fresh
flp_…for the host (e.g.floop keys create cursor-blog-only) and pass that key. Revoking it is one CLI call when you want to retire the workspace. -
Tell the model which
subdomainto use. Most tools take asubdomain_or_idargument; in the system prompt or first message, specify "only operate on the projectrecipe-blog." Models follow this consistently in practice. -
Use a team-scoped key. Team-scoped keys exist on the backend and the SDK takes
teamId, but the MCP tool args don't expose it yet — tracked behind the larger team-tools epic.
If you want hard scoping (the key literally cannot mint a new project), file an issue — it's a backend feature request, not an MCP one.
Only API keys today. The MCP spec gained OAuth support recently and we'll likely add it once Claude Desktop / Cursor support a stable host-side OAuth flow — until then, FLOOP_API_KEY is the only path. Generated keys are revocable from the dashboard, so leakage scope is bounded.
Three different things, often confused:
@floopfloop/mcp |
@floopfloop/sdk |
@floopfloop/ai |
|
|---|---|---|---|
| What it is | MCP server for LLM hosts | Node SDK for FloopFloop's management API | AI gateway client baked into deployed projects |
| Auth key |
FLOOP_API_KEY (flp_…) |
FLOOP_API_KEY (flp_…) |
FLOOPFLOOP_AI_KEY (flp_sk_…) |
| Audience | Claude / Cursor / Zed users | Devs writing Node code that talks to FloopFloop | Code running inside a deployed FloopFloop project |
| Distribution | npm — npx -y @floopfloop/mcp
|
npm — @floopfloop/sdk
|
Pre-installed inside generated projects, NOT on npm |
This MCP wraps @floopfloop/sdk. @floopfloop/ai is a completely separate package for projects to call the platform's LLM gateway from inside their own runtime — orthogonal to the MCP.
Probably not, and you probably don't want it to. The MCP server is interactive — its purpose is to give an LLM tools to call. In CI you don't have an LLM in the loop; you have a script. Use the floop CLI for the same tasks (floop create, floop refine, etc.) or one of the language SDKs.
If you genuinely have an LLM-driven CI pipeline (e.g. an autonomous bot that uses Claude API + tool-use to manage FloopFloop builds), call the SDK directly — that's two fewer hops than spinning up the MCP just to forward calls.
npx -y @floopfloop/mcp re-resolves to the latest version on every host launch. If you've pinned via npm install -g @floopfloop/mcp, run npm install -g @floopfloop/mcp@latest and restart your host.
CHANGELOG / version history lives at https://www.npmjs.com/package/@floopfloop/mcp?activeTab=versions and is generated from the SDK + MCP repo commits.
Open an issue. The bar for adding to this FAQ is "someone else might ask the same thing" — once is plenty.