PricingDocumentationDownload

MCP FAQ

TukeySheets ships an in-process MCP server and one-click toggles for the major MCP clients. The toggles are mostly "just work", but a few clients have setup quirks that bite people on first use. Everything on this page is from the field.

The TukeySheets MCP server

When ai.mcp_enabled is true(Settings → AI → "Enable MCP server"), TukeySheets binds 127.0.0.1:<mcp_port> and exposes a single POST /mcp endpoint that speaks the MCP JSON-RPC protocol. The server lives inside the app process — it starts when the first window opens and stops when the last window quits. It is loopback-only and unauthenticated; see the FAQ below for the security implications.

Changing the port in Settings restarts the server automatically and rewrites every enabled client's config with the new URL. You do not need to manually re-toggle anything.

Per-client cheat sheet

For each supported client: where TukeySheets writes the entry, what transport it uses, and what you need preinstalled.

Claude Desktop

stdio (via npx mcp-remote)
macOS
~/Library/Application Support/Claude/claude_desktop_config.json
Windows
%LOCALAPPDATA%\Packages\Claude_<hash>\LocalCache\Roaming\Claude\claude_desktop_config.json (MSIX / Microsoft Store) OR %APPDATA%\Claude\claude_desktop_config.json (traditional installer)
Linux
~/.config/Claude/claude_desktop_config.json
Prerequisites: Node.js (so npx is on PATH). The TukeySheets entry runs `npx mcp-remote http://127.0.0.1:<port>/mcp --allow-http`, which is a small shim that bridges Claude Desktop's stdio transport to the HTTP server.
  • Claude Desktop only speaks stdio — there is no native remote-HTTP option, so the npx shim is required even though TukeySheets is running on your own machine.
  • Windows installs come in two flavors: the traditional installer (config under %APPDATA%\Claude\) and the MSIX / Microsoft Store package (config under %LOCALAPPDATA%\Packages\Claude_<hash>\LocalCache\Roaming\Claude\). The MSIX package's view of %APPDATA% is virtualized by Windows into that LocalCache path, so a non-packaged app like TukeySheets has to write directly to the package folder — writing to plain %APPDATA%\Claude\ is invisible to MSIX Claude. TukeySheets auto-detects which is installed and writes to the right one; if you have both installed (unusual), it prefers the MSIX path.
  • After toggling the switch on, you must FULLY QUIT Claude Desktop (Cmd-Q on macOS; right-click the taskbar tray icon on Windows → Quit) and relaunch. Closing the window only hides it; the MCP config is read once at process start.
  • If TukeySheets does not show up in Claude Desktop's tool list, check the logs. Traditional installer: %APPDATA%\Claude\logs\. MSIX: %LOCALAPPDATA%\Packages\Claude_<hash>\LocalCache\Roaming\Claude\logs\. macOS: ~/Library/Logs/Claude/. A missing `npx` shows up as an ENOENT spawn error.
  • The first connection after a fresh Node install will pause for a few seconds while npx fetches the `mcp-remote` package from npm. Subsequent launches reuse the cached copy.

Claude Code (CLI)

stdio (via npx mcp-remote)
macOS
~/.claude.json
Windows
%USERPROFILE%\.claude.json
Linux
~/.claude.json
Prerequisites: Node.js (same npx shim as Claude Desktop).
  • Same stdio constraint as Claude Desktop, so the same npx requirement applies.
  • Claude Code re-reads ~/.claude.json on every invocation, so toggling the switch takes effect on your next `claude` command — no restart dance needed.

Codex CLI

remote HTTP
macOS
~/.codex/config.toml
Windows
%USERPROFILE%\.codex\config.toml
Linux
~/.codex/config.toml
Prerequisites: None.
  • Codex speaks remote HTTP natively, so TukeySheets writes a bare [mcp_servers.tukeysheets] TOML table with a `url` field — no npx, no Node.
  • If you have hand-edited config.toml, TukeySheets preserves comments and ordering on update (it edits the document, it does not rewrite it).

Gemini CLI

remote HTTP
macOS
~/.gemini/settings.json
Windows
%USERPROFILE%\.gemini\settings.json
Linux
~/.gemini/settings.json
Prerequisites: None.
  • Writes a bare `{ "url": "http://127.0.0.1:<port>/mcp" }` entry under mcpServers.tukeysheets.

OpenCode

remote HTTP
macOS
~/.config/opencode/opencode.json
Windows
%APPDATA%\opencode\opencode.json
Linux
~/.config/opencode/opencode.json
Prerequisites: None.
  • The entry uses `type: "remote"` (OpenCode's convention), not `"http"`. The toggle field is also set to `enabled: true` so OpenCode loads the server immediately.

Kiro CLI

remote HTTP
macOS
~/.kiro/settings/mcp.json
Windows
%USERPROFILE%\.kiro\settings\mcp.json
Linux
~/.kiro/settings/mcp.json
Prerequisites: None.
  • Bare `{ "url": ... }` entry under mcpServers.tukeysheets — same shape as Gemini.

FAQ

I flipped the Claude Desktop switch on but TukeySheets does not appear in the tool list.
Three things must be true: (1) Node.js is installed and `npx` is on the user PATH, (2) Claude Desktop was relaunched AFTER you installed Node — Claude captures PATH at process start, so an already-running instance won't see a Node install that happened later, and (3) on Windows, TukeySheets wrote to the right config path for your Claude install flavor. The Microsoft Store / MSIX version reads its config from %LOCALAPPDATA%\Packages\Claude_<hash>\LocalCache\Roaming\Claude\claude_desktop_config.json; the traditional installer reads from %APPDATA%\Claude\. TukeySheets auto-detects this, but if you installed Claude AFTER turning the toggle on, toggle it off and back on so the path is re-resolved.
How do I install npx on Windows?
npx ships with Node.js. Install Node from nodejs.org (LTS, the 64-bit .msi) or via winget (`winget install OpenJS.NodeJS.LTS`). Make sure the 'Add to PATH' option stays checked in the installer. Close and reopen any terminal, then run `npx --version` to verify. Finally, fully quit and relaunch Claude Desktop.
Does anything bind to a network port on my machine?
Yes — when the MCP server is enabled in Settings, TukeySheets binds 127.0.0.1:<mcp_port> (default 31337). It is loopback-only, so it is not reachable from your LAN or from the internet. You can change the port in Settings if 31337 conflicts with something else; the server restarts automatically when the port changes.
Is the server authenticated?
No. The built-in MCP server runs unauthenticated by design — there is no portable way to hand a rotating per-start token to every external MCP client. The implication on a multi-user machine is that any local process running as another user account can call your MCP tools while TukeySheets is running. If that is a concern, disable the MCP server when you are not actively using it.
I changed the MCP port in Settings but my external client still hits the old port.
TukeySheets rewrites every enabled client's config when the port changes, but the clients themselves cache the URL until they reload. For Claude Desktop, fully quit and relaunch. For Codex / Gemini / Kiro / OpenCode, the next invocation will pick up the new URL.
I see TukeySheets listed in my client's tools but every call times out.
Confirm the TukeySheets app is running and unlocked — the MCP server is in-process, so closing the app stops the server. If the app is running and the call still times out, check that the port in the client's config matches the `mcp_port` in TukeySheets Settings. Mismatches can happen if you edited config files by hand.
Can I run multiple TukeySheets windows at once?
Yes, but only one of them owns the MCP port. The first window to start the standalone server binds the port; later windows skip binding (the bind fails with EADDRINUSE and the server is not started). All windows share the same underlying state, so this is normally invisible — but if you quit only the first window the server goes down with it, and subsequent windows will not automatically take over.
I uninstalled TukeySheets but Claude Desktop / Codex / etc. still lists 'tukeysheets'.
TukeySheets only writes its own entries; it does not run a cleanup hook on uninstall. Open the client's config file (paths above) and delete the `tukeysheets` entry under `mcpServers` (or `mcp_servers` for Codex's TOML, or `mcp` for OpenCode). The rest of the file is preserved when TukeySheets edits it, so removing one key is safe.
Does the toggle write to per-machine or per-user configs?
Per-user only. All paths under %APPDATA%, %USERPROFILE%, or the user's home directory. TukeySheets never touches %PROGRAMDATA% or /etc.
Why is the JSON key `tukeysheets` and not `tukey`?
The server name written into every client config is the literal string `tukeysheets`. Older comments may say `tukey` — that is stale documentation, not a bug.