Docs

Tool Surface Setup

FlyDocs ships an MCP server and a command runner so your coding agent works your issue tracker with typed tool calls instead of shell commands.

FlyDocs ships a small MCP server and a command runner so your coding agent can work your issue tracker with typed tool calls instead of shell commands. Both are set up for you by flydocs init and flydocs update. This guide covers what those commands write into your repo, why each write is safe, and how to check the result.

What You End Up With

You get Reached as
The lifecycle tools, in your editor flydocs mcp (stdio MCP server)
Every other workflow operation flydocs run <operation-id>
No approval prompt for either Two standing rules in your settings

The server is spawned by your editor, over stdio, on demand. Nothing listens on a port, and nothing runs in the background.

The Setup Sequence

Terminal 
npm install -g @flydocs/cli     # 1.3.4 or later
cd your-project
flydocs init                    # registers the server, records the interpreter
flydocs update                  # writes the managed permission block
flydocs doctor --tools          # verifies all of it

flydocs init registers flydocs mcp with Claude Code and Cursor and resolves the Python interpreter once, here, where you are watching — rather than on the hot path of the first tool call. flydocs update does that again (idempotently) and additionally writes the managed permission block.

Restart your editor after the first run. MCP registrations are read at startup; a running editor will not notice a new .mcp.json.

Enabling in Cursor

Cursor requires a one-time enable for a newly registered project server. After flydocs init writes .cursor/mcp.json, open Settings → Cursor Settings → MCP and toggle the flydocs server on. You only do this once per project.

Alternatively, use the one-click install link: Add FlyDocs to Cursor — it registers the same flydocs mcp entry and prompts you to enable it in one step.

What Gets Written

File Written by Contents
.mcp.json init, update A flydocs entry under mcpServers → flydocs mcp
.cursor/mcp.json init, update The same entry, with "type": "stdio" (Cursor's schema)
.claude/settings.json update Two permissions.allow rules + a flydocsManaged record
.claude/.flydocs-backup/ update A copy of the settings file taken before any write
.flydocs/config.json → runtime init, update The Python interpreter found on this machine; never sent to the server

.mcp.json and .cursor/mcp.json are not gitignored — they describe the project's servers and are meant to be committed, so a teammate who clones the repo gets the same tools. .claude/settings.json and the backup directory are gitignored: they are per-machine.

Claude Code's .mcp.json is also read by Windsurf and by VS Code's agent mode, so two files cover four clients.

In a multi-repo workspace

Registrations are written into each repo and at the workspace root. An editor reads the registration from whatever directory it was opened in, and flydocs mcp resolves its repo from the same directory, so a child repo you can open on its own needs its own copy.

Why Each Write Is Safe

  • Your other MCP servers survive. Only the flydocs key inside mcpServers is ever read or written. When the entry is already correct, nothing is written at all — a repeat flydocs update leaves the file byte-identical.
  • A file FlyDocs cannot read is never overwritten. An .mcp.json with a syntax error may still hold half your team's server list; FlyDocs reports it and leaves it alone. Same for .claude/settings.json.
  • The permission block is replaced atomically, after a backup. The settings file is written to a temporary file, flushed, and renamed — a torn settings file would silently disable your hooks as well as your permissions. The previous content is copied under .claude/.flydocs-backup/ before the first byte changes.
  • Rules are removed only on an exact match. FlyDocs records exactly which rules it wrote, under a top-level flydocsManaged key. A rule you wrote yourself is never removed, even if it looks similar. See Managed Permissions for the modes and fields.
  • Nothing machine-specific reaches the server. The resolved Python interpreter is stored under a runtime key that is CLI-local, preserved across syncs, and never part of what your workspace syncs up.

Options Worth Knowing

Flag Effect
flydocs update --no-overwrite Keep an existing flydocs MCP entry instead of replacing it
flydocs doctor --tools Run only the tool-surface checks
flydocs doctor --tools --fix Repair what FlyDocs owns, then re-check everything
flydocs doctor --json The same results as one JSON document, for CI
flydocs mcp --verbose Run the server by hand with tool calls logged to stderr

What flydocs doctor Verifies

flydocs doctor --tools answers the questions this setup cannot answer for itself. Every check has a stable ID, and those IDs are what the Troubleshooting guide is organised by.

ID Question it answers
surface.scope Which directory is being examined
mcp.server Does this build's server complete a real handshake
mcp.tools-budget Does the tool list stay inside its context budget
mcp.command Is flydocs on PATH, and new enough to serve mcp
mcp.registration.claude Does .mcp.json point at flydocs mcp
mcp.registration.cursor Does .cursor/mcp.json point at flydocs mcp
permissions.settings Does .claude/settings.json parse
permissions.block Is the managed block present and current
run.registry Do the operation registry and its entrypoints load
run.interpreter Can flydocs run find a Python 3 interpreter
run.dry-run Does an operation resolve end to end
runtime.python Does the recorded interpreter still exist

Exit code is 0 if and only if nothing failed; warnings never fail the command, which makes flydocs doctor --tools safe to put in CI.

What FlyDocs Does Not Do Here

  • It does not run a server in the background, or open a port.
  • It does not ask for OAuth. On stdio, credentials come from the environment and from ~/.flydocs/credentials — which is what the MCP specification prescribes for local servers.
  • It does not probe your PATH during init or update. That question — "is the flydocs your editor will spawn the same one that wrote this file?" — belongs to flydocs doctor, and is mcp.command.
  • It does not touch any MCP server entry other than flydocs, or any permission rule it did not write.

Next