Developer platform

MCP server

A thin, local MCP server that speaks to your AI coding agent on one side and the Goosy scan engine on the other — no scanning logic runs on your machine.

goosy-mcp is a local stdio process your MCP host (Claude Code, Claude Desktop, Cursor) spawns — no separate service to run. Every tool call becomes an authenticated request to Goosy's API; the package itself holds no rules and makes no model calls.

Install

npm

npm i goosy-mcp

Or skip the install step entirely and let your MCP host fetch it on demand with npx — both work with the same config below.

Add it to your MCP host

Claude Code / Claude Desktop / Cursor — MCP server config

{
  "mcpServers": {
    "goosy": {
      "command": "npx",
      "args": ["-y", "goosy-mcp"],
      "env": { "GOOSY_API_BASE": "https://api.goosy.ai" }
    }
  }
}

Already ran npm i goosy-mcp? Point command at the installed binary directly instead of going through npx — for a global install (npm i -g goosy-mcp), that's just "command": "goosy-mcp", "args": [].

Authenticate

npx goosy-mcp login     # opens a device-code flow in your browser
npx goosy-mcp doctor    # verifies config, auth, and backend reachability

Or skip login entirely

The first tool call without a valid token returns a structured AUTH_REQUIRED error carrying a verification URL and a short code, written for the agent to relay to you directly in the conversation — approve it once in your browser and the agent's retry just works. Concurrent tool calls share the same pending device code rather than issuing a confusing second one.

The six tools

Tool	What it does
`goosy_scan_local`	Bundles the working tree — including uncommitted files — and starts a scan. Returns a `scan_id` immediately.
`goosy_scan_status`	Polls scan state and progress; carries `retry_after_seconds` so an agent paces its own polling.
`goosy_list_findings`	Paginated, summary-shaped findings with severity and path filters.
`goosy_get_finding`	Full detail on one finding — snippet, CWE, call path, remediation.
`goosy_generate_fix`	Returns a unified diff as text for the agent to review and apply.
`goosy_explain_finding`	Prose explanation with references, for justifying a change to a human.

Goosy returns data; the agent acts

goosy_generate_fix hands back a patch as text — this server never writes to your filesystem, commits, or opens a pull request. There is no create_pr, apply_patch, or dismiss_finding tool: an agent acting in a loop must not be able to mutate your repository or silently suppress a security finding unattended. This is enforced mechanically in the package's own test suite, not just documented.

Security model

Risk	Control
Secrets uploaded from the working tree	A path- and content-signature deny-list applies after `.gitignore` and overrides it — a git-tracked `.env` is still refused. The backend re-checks on ingest.
Agent steered to scan outside the project	Every path is resolved and confined to the workspace root; `/`, `~`, `..`, and symlink escapes are rejected.
Unattended repository mutation	No write tool exists.
Over-large bundles	Hard caps on file count and total size. Going over is an error with the actual numbers — never a silent truncation, since a partial scan reported as complete is a false clean bill of health.
Runaway agent cost	`retry_after_seconds` on pending responses, plus server-side ceilings.

Two invariants worth knowing as a user: a failed scan is always reported as failed, never as “clean” — the difference between “your code is clean” and “we didn't look” is the point of the tool — and every excluded file is counted and reported back in the tool response's warnings, not silently dropped.

Token storage

Tokens live at ${XDG_CONFIG_HOME:-~/.config}/goosy/config.json (%APPDATA%\goosy\config.json on Windows), mode 0600, keyed by API base so production and a local stack can coexist — the same path the CLI uses, so a goosy login from the terminal may already satisfy this. Refresh on expiry is transparent and serialized by a file lock so two processes can't race a rotation.

Already have the CLI installed?

The Goosy CLI also has a built-in goosy mcp subcommand that starts an MCP server in-process, reusing whatever session goosy login already created. Reach for goosy-mcp (this page) when you just want MCP without installing the CLI binary first.

Package: npmjs.com/package/goosy-mcp

← CLI