Local Codex and Claude Code integration for ApyGuard APIScout. The plugin scans backend source code, returns structured API inventory findings, prepares endpoint evidence and exact source locations for the active agent, opens an interactive asset creation form, exports OpenAPI, and compares OpenAPI documents. It does not require VS Code, but it requires an ApyGuard browser sign-in before scan, findings, endpoint context, export, or comparison tools can run.
- Installation
- First use
- What the plugin does
- Where your data goes
- Known limitations
- Updates
- Development and releases
- Security and support
- Legal
- Codex (CLI or desktop app) or Claude Code (CLI or desktop app)
uv, which also fetches the Python 3.13 runtime the plugin needs- A supported platform:
| Platform | Support |
|---|---|
| macOS on Apple silicon | Supported |
| macOS on Intel | Supported |
| Linux x86-64 | Supported with glibc 2.28 or newer, such as AlmaLinux 8, Ubuntu 22.04, or Debian 12 |
| Windows | Through WSL, with a distribution that meets the Linux requirement |
| Linux arm64 | Not supported |
The MCP server launcher is a POSIX shell script, so native Windows is not
supported yet. Run Claude Code inside WSL, or switch the Codex desktop app's
agent to WSL in Settings, and install uv inside WSL.
The plugin's Python packages are not published on PyPI. It installs them only from
the wheels in this repository, so do not install apyguard-engine or
apyguard-apiscout-plugin from a package index.
Add the public ApyGuard plugin marketplace and install the plugin:
codex plugin marketplace add ApyGuard/APIScout-Plugincodex plugin add apyguard-apiscout-plugin@apyguard-apiscoutIf macOS reports codex: command not found while using the Codex desktop app,
add the bundled CLI to the current shell session and run the commands again:
export PATH="/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin:$PATH"The plugin can also be installed from the Plugins screen in the Codex desktop
app by adding the public ApyGuard/APIScout-Plugin marketplace.
Once the marketplace is added, this link opens the plugin's install screen in
the Codex desktop app. Paste it into your browser, or run open "<link>" on
macOS:
codex://plugins/install/apyguard-apiscout-plugin?marketplace=apyguard-apiscout
Add the same marketplace and install the plugin for your user:
claude plugin marketplace add ApyGuard/APIScout-Pluginclaude plugin install apyguard-apiscout-plugin@apyguard-apiscoutClaude Code does not update plugins from third-party marketplaces unless
auto-update is enabled for that marketplace. To receive new releases
automatically, run claude in a terminal, open /plugin, go to
Marketplaces, select apyguard-apiscout, and choose Enable auto-update.
The setting also applies to the Code tab of the Claude desktop app.
To try a local checkout without installing it, start Claude Code from the project you want to scan and load the plugin directory for that session only:
claude --plugin-dir /absolute/path/to/apyguard-apiscout-pluginAfter installation, start a new chat in your client and paste one of these prompts:
Scan this project with APIScout and summarize the API findings.
Open the APIScout Workbench for this project.
Show high-sensitivity API findings in this project.
Explain the GET /users/{user_id} endpoint using source evidence and open its source.
Review the GET /users/{user_id} endpoint, suggest a correction, and add the suggestion as a TODO at its source line.
Review and fix this project's APIScout findings.
Run the full API security pipeline with APIScout for this project.
Export this project's OpenAPI document to openapi.json.
Compare /absolute/path/previous.json with /absolute/path/current.json.
Open the ApyGuard asset creation form for this project.
List the ApyGuard asset and API collections for this project.
Has the ApyGuard import or live scan of this project finished?
Use the project root as the path when a prompt needs an explicit path. The first APIScout request starts the browser login automatically when needed; after returning from the connected page, repeat the prompt. Claude Code users can also use the bundled commands shown by the plugin command list.
In MCP Apps-compatible clients, open_api_workbench adds a compact interactive
workbench with scan summary metrics, finding severity filters, endpoint evidence
actions, and an export entry point. The separate asset form collects metadata and
uploads the generated OpenAPI document. The same tools remain structured results
in text-only clients, including CLI-oriented environments.
The MCP server signs in to ApyGuard with a device sign-in. start_apyguard_login
returns a login URL and a short code; you sign in to ApyGuard in the browser,
check that the page shows the same code, and approve it. The next APIScout
request finishes the sign-in and receives an access token for this installation
of the plugin. Tokens are stored outside the repository in separate owner-only
files under ~/.config/apyguard/apiscout/, stop working after 90 days without
use, and can be revoked from ApyGuard's integration settings; sign_out_apyguard
revokes the token. Set APYGUARD_APISCOUT_API_URL to use another ApyGuard API,
such as an on-premises installation. The token is sent only to the API that
issued it.
- Scans local backend source code and summarizes its API surface.
- Reviews inventory findings with source-backed endpoint evidence.
- Opens the interactive APIScout Workbench.
- Fixes approved findings in source and verifies them with a rescan, through the
review-and-fixskill. - Takes a project from static review through an ApyGuard live scan and back to
source, through the
full-pipelineskill. You start the scan in ApyGuard and share its findings. - Creates one ApyGuard asset per project and imports later documentation into it.
- Lists a project's asset and collections, and reports whether its latest import and live scan have finished.
- Exports and compares OpenAPI documents.
On your computer. The MCP server and the APIScout engine run locally. Scans,
exports, and comparisons read and write local files, and do not upload them. The
plugin stores its runtime under ~/.cache/apyguard/apiscout/, or under
XDG_CACHE_HOME when that is set.
What the plugin downloads. The first time the plugin starts, uv builds its
runtime. The plugin and the engine come from the wheels in this repository. The
third-party Python packages they depend on come from PyPI
(files.pythonhosted.org), pinned to the exact versions and hashes in the
platform's uv.lock. If Python 3.13 is not installed, uv also downloads it from
Astral's python-build-standalone releases on GitHub. Later starts reuse the
runtime, and an update downloads only the packages that are not already in uv's
cache.
To your AI model provider. Tool results become part of your Codex or Claude
Code conversation, and your client sends them to its model provider under that
provider's terms. These results include API routes, findings, local file paths,
and, from review_api_project and get_endpoint_context, source code excerpts of
up to 12,000 characters per endpoint. The plugin does not call an AI provider
itself. Do not scan code that your agreement with your model provider does not
allow you to share.
To ApyGuard.
- Signing in sends the client type and a random installation id.
- Listing an asset or reading progress sends an identifier derived from the project's absolute path.
- Creating an asset or importing documentation also sends the asset details you enter and the generated OpenAPI document. That happens only when you submit the form or ask for it. The document holds routes, schemas, descriptions taken from the code, findings, and source file paths relative to the project, but not source files or excerpts.
See the Privacy Policy for how ApyGuard handles this information.
- Asset form in the Claude desktop app's Code tab. The form renders, but
submitting it can fail with
IPC not available for MCP tool call. Ask the agent in chat to create the asset instead, or use the Chat tab. - Assets follow the project's path and client. An asset belongs to the project's absolute path and to the client that created it, so another checkout or client does not see it.
- Authentication evidence. Only the
djangoframework reports endpoint authentication today. For other frameworks, a missing value says nothing about whether the endpoint is protected.
Each release is tagged plugin-v<version> in this repository, for example
plugin-v0.1.6, and new installs get the latest tagged release. The
changelog lists what changed. Claude Code updates the plugin on
its own only when auto-update is enabled (see Claude Code);
otherwise, and for Codex, follow the steps for the client you use.
claude plugin list | grep -A3 apyguardls ~/.codex/plugins/cache/apyguard-apiscout/apyguard-apiscout-plugin/The first command shows the Claude Code version, the second lists the Codex
versions on disk. If it already matches the latest plugin-v* tag, you are up
to date.
Claude Code (terminal and the Code tab of the Claude desktop app):
claude plugin marketplace update apyguard-apiscoutclaude plugin update apyguard-apiscout-plugin@apyguard-apiscoutCodex (CLI and desktop app). If codex is not found, add the bundled CLI to
the current shell first:
export PATH="/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin:$PATH"codex plugin marketplace upgrade apyguard-apiscoutcodex plugin add apyguard-apiscout-plugin@apyguard-apiscout- Claude Code: quit the Claude desktop app completely (Cmd+Q on macOS) and
reopen it, or start a new
claudesession in the terminal. - Codex: start a new chat so the new skills and MCP tools are loaded.
Run the version check from step 1 again; it should show the new version. Then
try a prompt such as Scan this project with APIScout and summarize the API findings.
The first request after an update can take a few seconds longer while the new
runtime is prepared. Your ApyGuard login is kept, so you do not need to sign in
again.
-
Claude Code says
already at the latest version: runclaude plugin marketplace update apyguard-apiscoutagain, then retry the update. If it still shows the old version, the new release has not been published yet. -
Codex keeps the old version: remove the plugin and add it again:
codex plugin remove apyguard-apiscout-plugin@apyguard-apiscout
codex plugin add apyguard-apiscout-plugin@apyguard-apiscout
-
APIScout tools are missing after the update: make sure you restarted the client (step 3); a running session keeps the version it started with.
Repository layout:
apyguard-apiscout-plugin/
├── src/ # Local MCP package and UI resources
├── skills/ # Agent skills for both clients
├── commands/ # Claude Code commands
├── scripts/ # MCP launcher and release scripts
├── tests/
├── legal/ # Plugin privacy policy and terms of service
├── .claude-plugin/ # Claude Code manifest, MCP configuration, and marketplace
├── .codex-plugin/ # Codex plugin manifest
├── .mcp.json # MCP configuration for Codex
└── releases/ # Per-platform runtime lockfiles and plugin/engine wheels
├── darwin-arm64/
├── darwin-x64/
├── linux-x64/
└── win32-x64/
Installed copies use only the wheels and lockfile under releases/<platform>/.
The launcher picks them for the current platform. Codex starts the server from the
root .mcp.json as the codex client. Claude Code reads
.claude-plugin/plugin.json, which points to .claude-plugin/.mcp.json and starts
the same server as the claude_code client.
The engine is not on a package index, so uv sync does not work at the repository
root. Run the tests in your platform's runtime, with this checkout's source on the
path:
PYTHONPATH=src uv run --project releases/darwin-arm64/runtime --locked --with 'pytest>=8.3,<9' python -m pytest -q -p no:cacheproviderThe ci workflow runs the same command on every pull request.
Codex and Claude Code install a new copy only when the plugin version changes,
so every release increases the version. The release workflow in this
repository is the only writer of the version and of releases/:
- Engine releases: a new engine release builds the wheels for all four
platforms and sends an
engine-releasedevent here. Thereleaseworkflow then bundles those wheels and increases the patch version. - Plugin-only releases: run the
releaseworkflow manually from the Actions tab. Choose the version part to increase, and leaveengine_tagempty to keep the current engine wheels.
Each run increases the version and rolls the changelog's Unreleased section
(scripts/bump_version.py), syncs both manifests and points the marketplace at the
new tag (scripts/sync_version.py), builds the plugin wheel once, places it with
each platform's engine wheel under releases/ (scripts/assemble_release.py), and
relocks each runtime with the latest allowed dependencies. It then runs the tests
and scripts/smoke_mcp.py against the linux-x64 runtime, commits, tags
plugin-v<version>, pushes to main, and publishes a GitHub release. Runs are
serialized, and the push fails instead of overwriting when main moved during the
run.
Merged changes reach users only through a release, because the marketplace points at the release tag.
Required secrets:
ENGINE_RELEASE_TOKENin this repository: a fine-grained token with read-only Contents access to the engine repository, used to download engine wheels from its releases.APISCOUT_PLUGIN_TOKENin the engine repository: a token with Contents write access to this repository, used to send theengine-releasedevent.
- Report vulnerabilities privately as described in SECURITY.md.
- For bugs and questions, open an issue in this repository or write to support@apyguard.com.
- ApyGuard APIScout Plugin Privacy Policy
- ApyGuard APIScout Plugin Terms of Service
- License: the plugin's own code is licensed under the Apache License, Version 2.0. The bundled APIScout Engine wheels and the ApyGuard and APIScout logos are not; NOTICE lists them and the terms that apply instead.
The Plugin is intended for authorized API discovery and documentation work. Do not scan source code, APIs, or systems that you do not own or have permission to assess.