Skip to content
Back to search

iii

MarketplaceWorks with Claude CodeGitHub

Claude Code plugin marketplace for the iii engine: the iii plugin (agent profiles, skills and the engine through mcp-server).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/iii-hq/agent-plugins-claude with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/iii-hq/agent-plugins-claude'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/iii-hq--agent-plugins-claude/badge.svg)](/listings/iii-hq--agent-plugins-claude)

HTML

<a href="/listings/iii-hq--agent-plugins-claude"><img src="/api/listings/iii-hq--agent-plugins-claude/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Skip this section** if your project was created by the iii `install.sh` script or from the harness template: it comes preconfigured, with mcp-server running behind rbac-proxy at `http://127.0.0.1:3111/mcp`. Go straight to [Install the plugin](#install-the-plugin). To check, run `iii call compose::status` in the project directory: if it lists `mcp-server`, the project is already set up.

The plugin talks to the engine through the `mcp-server` worker, and mcp-server only starts behind `rbac-proxy`, which decides what agents may call. One-time setup, in your iii project directory (commands assume the `default` namespace and the engine on its default port, `ws://127.0.0.1:49134`).

1. Add rbac-proxy and the http worker, on this machine only

iii call compose::add --json '{"workers": ["rbac-proxy", "secrets", {"worker": "http", "config_override": {"host": "127.0.0.1"}}]}'

- The http worker listens on every interface (`0.0.0.0`) by default, and mcp-server refuses to serve an endpoint other machines can reach. `config_override` binds it to `127.0.0.1` and keeps the rest of its settings; compose applies it every time http starts. If the project already has http, this updates it and restarts it. - If your `worker-compose.yaml` already gives http a `config_override` (a custom port, say), this command replaces it with just the host. In that case, add `host: 127.0.0.1` to your existing `config_override` in `worker-compose.yaml` by hand instead, and add `rbac-proxy` and `secrets` on their own. - `secrets` backs the `iii_secret_store` tool.

2. Configure rbac-proxy

rbac-proxy's settings live in the configuration worker, under `default-rbac-proxy`:

iii call configuration::set --json '{
  "id": "default-rbac-proxy",
  "value": {
    "host": "127.0.0.1",
    "port": 49200,
    "engine_url": "ws://127.0.0.1:49134",
    "rbac": {
      "loopback_auth": {
        "worker_names": ["mcp-server"],
        "forbidden_functions": ["secrets::resolve"]
      },
      "expose_endpoints": ["match(\"/\")", "match(\"/ws/channels/*\")", "match(\"/otel\")"],
      "expose_functions": ["match(\"*\")"]
    }
  }
}'

- `loopback_auth` admits connections from this machine only, with no auth function or token to set up: every local process can already reach the engine port directly. It lets mcp-server keep its own name, and keeps `secrets::resolve` away from agents (it would let them read every secret). For an engine others reach over the network, see [Remote or shared engines](#remote-or-shared-engines). - `port` is where mcp-server connects (step 4); `engine_url` is your engine. - `expose_endpoints`: which engine endpoints rbac-proxy serves. It serves none until you list them. `/` is required; `/otel` carries mcp-server's logs and traces; `/ws/channels/*` is for functions that stream. - `expose_functions`: what agents may call. `match("*")` is everything; narrow it to limit agents, for example `["match(\"orders::*\")", "match(\"secrets::set\")"]`.

3. Restart rbac-proxy

rbac-proxy reads the new settings live, but rule changes only apply to new connections. Restart it so every connection uses them:

iii call compose::restart container=rbac-proxy
iii call rbac-proxy::status

`rbac-proxy::status` should show `auth: "loopback"` and the three endpoints.

Do the same after any later change to its settings: `configuration::set`, then `compose::restart container=rbac-proxy` and `compose::restart container=mcp-server`.

4. Add mcp-server

Point it at rbac-proxy's port, not the engine's:

iii call compose::add --json '{"workers": [{"worker": "mcp-server", "environment": {"III_MCP_ENGINE_URL": "ws://127.0.0.1:49200"}}]}'

It serves MCP at the http worker's address plus `/mcp`: `http://127.0.0.1:3111/mcp` by default (`iii call http::status` shows the address). If yours differs, install the plugin with `--config mcp_url=...` (see [Install the plugin](#install-the-plugin)).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "iii",
  4. "owner": {
  5. "name": "iii-hq",
  6. "url": "https://github.com/iii-hq"
  7. },
  8. "metadata": {
  9. "description": "Claude Code plugins for the iii engine."
  10. },
  11. "plugins": [
  12. {
  13. "name": "iii",
  14. "source": "./plugins/iii",
  15. "description": "Agent profiles, skills and the engine itself from a running iii engine, through its mcp-server worker. Works inside the claude-code worker and in a standalone claude.",
  16. "license": "Apache-2.0",
  17. "homepage": "https://github.com/iii-hq/agent-plugins-claude",
  18. "repository": "https://github.com/iii-hq/agent-plugins-claude"
  19. }
  20. ]
  21. }
README.md · README · 267 lines
  1. # iii plugins for Claude Code
  2. The `iii` plugin connects Claude Code to a running [iii](https://github.com/iii-hq) engine.
  3. It adds the engine's MCP tools (`iii_call`, `iii_observe`, profiles and skills), starts every
  4. session on the engine's `default-mcp` agent profile, and gives you `/iii:profile`,
  5. `/iii:skills` and one `/iii:<profile>` command per visible profile. Every call goes through
  6. the engine's [`mcp-server`](https://github.com/iii-hq/workers/tree/main/mcp-server) worker,
  7. so rbac-proxy's rules apply. Details: [plugins/iii/README.md](plugins/iii/README.md).
  8. ## Set up iii to serve it
  9. **Skip this section** if your project was created by the iii `install.sh` script or from
  10. the harness template: it comes preconfigured, with mcp-server running behind rbac-proxy at
  11. `http://127.0.0.1:3111/mcp`. Go straight to [Install the plugin](#install-the-plugin). To
  12. check, run `iii call compose::status` in the project directory: if it lists `mcp-server`,
  13. the project is already set up.
  14. The plugin talks to the engine through the `mcp-server` worker, and mcp-server only
  15. starts behind `rbac-proxy`, which decides what agents may call. One-time setup, in your
  16. iii project directory (commands assume the `default` namespace and the engine on its
  17. default port, `ws://127.0.0.1:49134`).
  18. ### 1. Add rbac-proxy and the http worker, on this machine only
  19. ```sh
  20. iii call compose::add --json '{"workers": ["rbac-proxy", "secrets", {"worker": "http", "config_override": {"host": "127.0.0.1"}}]}'
  21. ```
  22. - The http worker listens on every interface (`0.0.0.0`) by default, and mcp-server refuses
  23. to serve an endpoint other machines can reach. `config_override` binds it to
  24. `127.0.0.1` and keeps the rest of its settings; compose applies it every time http
  25. starts. If the project already has http, this updates it and restarts it.
  26. - If your `worker-compose.yaml` already gives http a `config_override` (a custom port, say),
  27. this command replaces it with just the host. In that case, add `host: 127.0.0.1` to
  28. your existing `config_override` in `worker-compose.yaml` by hand instead, and add
  29. `rbac-proxy` and `secrets` on their own.
  30. - `secrets` backs the `iii_secret_store` tool.
  31. ### 2. Configure rbac-proxy
  32. rbac-proxy's settings live in the configuration worker, under `default-rbac-proxy`:
  33. ```sh
  34. iii call configuration::set --json '{
  35. "id": "default-rbac-proxy",
  36. "value": {
  37. "host": "127.0.0.1",
  38. "port": 49200,
  39. "engine_url": "ws://127.0.0.1:49134",
  40. "rbac": {
  41. "loopback_auth": {
  42. "worker_names": ["mcp-server"],
  43. "forbidden_functions": ["secrets::resolve"]
  44. },
  45. "expose_endpoints": ["match(\"/\")", "match(\"/ws/channels/*\")", "match(\"/otel\")"],
  46. "expose_functions": ["match(\"*\")"]
  47. }
  48. }
  49. }'
  50. ```
  51. - `loopback_auth` admits connections from this machine only, with no auth function or
  52. token to set up: every local process can already reach the engine port directly. It
  53. lets mcp-server keep its own name, and keeps `secrets::resolve` away from agents (it
  54. would let them read every secret). For an engine others reach over the network, see
  55. [Remote or shared engines](#remote-or-shared-engines).
  56. - `port` is where mcp-server connects (step 4); `engine_url` is your engine.
  57. - `expose_endpoints`: which engine endpoints rbac-proxy serves. It serves none until you
  58. list them. `/` is required; `/otel` carries mcp-server's logs and traces; `/ws/channels/*`
  59. is for functions that stream.
  60. - `expose_functions`: what agents may call. `match("*")` is everything; narrow it to limit
  61. agents, for example `["match(\"orders::*\")", "match(\"secrets::set\")"]`.
  62. ### 3. Restart rbac-proxy
  63. rbac-proxy reads the new settings live, but rule changes only apply to new connections.
  64. Restart it so every connection uses them:
  65. ```sh
  66. iii call compose::restart container=rbac-proxy
  67. iii call rbac-proxy::status
  68. ```
  69. `rbac-proxy::status` should show `auth: "loopback"` and the three endpoints.
  70. Do the same after any later change to its settings: `configuration::set`, then
  71. `compose::restart container=rbac-proxy` and `compose::restart container=mcp-server`.
  72. ### 4. Add mcp-server
  73. Point it at rbac-proxy's port, not the engine's:
  74. ```sh
  75. iii call compose::add --json '{"workers": [{"worker": "mcp-server", "environment": {"III_MCP_ENGINE_URL": "ws://127.0.0.1:49200"}}]}'
  76. ```
  77. It serves MCP at the http worker's address plus `/mcp`: `http://127.0.0.1:3111/mcp` by
  78. default (`iii call http::status` shows the address). If yours differs, install the plugin
  79. with `--config mcp_url=...` (see [Install the plugin](#install-the-plugin)).
  80. ### Remote or shared engines
  81. `loopback_auth` trusts every process on this machine. When other people or machines can
  82. reach rbac-proxy, give it an auth function instead (`rbac.auth_function_id`, which takes
  83. precedence over `loopback_auth`): a function you register that checks each connection,
  84. for example a bearer token, and returns its grants. See
  85. [rbac-proxy](https://github.com/iii-hq/workers/tree/main/rbac-proxy) for the function's
  86. input and answer, and [mcp-server](https://github.com/iii-hq/workers/tree/main/mcp-server)
  87. for sending a token from mcp-server (`III_TOKEN`).
  88. ## Install the plugin
  89. In Claude Code:
  90. ```
  91. /plugin marketplace add iii-hq/agent-plugins-claude
  92. /plugin install iii@iii
  93. ```
  94. From a shell:
  95. ```sh
  96. claude plugin marketplace add iii-hq/agent-plugins-claude
  97. claude plugin install iii@iii
  98. ```
  99. When mcp-server is not at the default `http://127.0.0.1:3111/mcp`, pass its address:
  100. ```sh
  101. claude plugin install iii@iii --config mcp_url=http://127.0.0.1:3211/mcp
  102. ```
  103. The plugin needs Node 22+ for its SessionStart hooks, and the engine's `mcp-server` worker
  104. behind rbac-proxy: [set that up first](#set-up-iii-to-serve-it). The `claude-code` worker already carries this plugin; you only
  105. install it for a standalone `claude`.
  106. Update or remove it:
  107. ```sh
  108. claude plugin marketplace update iii
  109. claude plugin update iii@iii
  110. claude plugin uninstall iii@iii
  111. ```
  112. ## Check it
  113. Start `claude` and run `/iii:profile`: it shows the active profile (`default-mcp`) and the
  114. profiles on your engine. `/mcp` lists the `iii` server as connected.
  115. If mcp-server does not start, its log says why (`iii call compose::status` shows its state):
  116. usually rbac-proxy is not configured yet (steps 2 and 3) or the http worker is not on
  117. `127.0.0.1` (step 1). Full reference:
  118. [mcp-server](https://github.com/iii-hq/workers/tree/main/mcp-server) and
  119. [rbac-proxy](https://github.com/iii-hq/workers/tree/main/rbac-proxy).
  120. ## Troubleshooting
  121. Every error from the plugin ends with a one-line fix and a link to one of these entries.
  122. First, check the project is running: `iii call compose::status` in the project directory
  123. lists each worker's state. `iii call compose::logs container=mcp-server` (or
  124. `container=rbac-proxy`) shows a worker's log.
  125. ### mcp-server is not reachable
  126. Nothing answers at the plugin's `mcp_url` (default `http://127.0.0.1:3111/mcp`).
  127. 1. Start the project: `iii compose --up` in the project directory.
  128. 2. Check that `http`, `rbac-proxy` and `mcp-server` are `ready` in `iii call compose::status`.
  129. If mcp-server is missing, follow [Set up iii to serve it](#set-up-iii-to-serve-it).
  130. 3. If mcp-server runs on another address, `iii call http::status` shows the http worker's
  131. address; install the plugin with that address plus `/mcp`
  132. (`claude plugin install iii@iii --config mcp_url=...`, see
  133. [Install the plugin](#install-the-plugin)).
  134. ### mcp-server does not answer at the address
  135. The address answers (HTTP 404, 502, ...), but not as mcp-server.
  136. 1. Check `mcp_url` ends with mcp-server's `api_path` (`/mcp` by default).
  137. 2. Read the mcp-server log. It withdraws `/mcp` and says why when:
  138. - it is not behind rbac-proxy, or rbac-proxy refuses it: set up steps 2 and 3 of
  139. [Set up iii to serve it](#set-up-iii-to-serve-it);
  140. - the http worker listens beyond this machine: bind it to `127.0.0.1` (step 1);
  141. - it cannot watch the http worker's reloads: allow `http::on-config-change` in
  142. rbac-proxy's `expose_functions`, then restart rbac-proxy and mcp-server.
  143. 3. After a fix, restart mcp-server: `iii call compose::restart container=mcp-server`.
  144. ### mcp-server refused the Origin
  145. HTTP 403: the request came with an `Origin` header mcp-server does not allow (browser-based
  146. clients send one; Claude Code does not). Add that origin (for example
  147. `https://app.example.com`) to `allowed_origins` in mcp-server's configuration, then restart
  148. it.
  149. ### mcp-server refused a new session
  150. HTTP 503: mcp-server is at its session limit (`max_sessions`, 16 by default).
  151. 1. Close other MCP clients you do not need, or wait: idle sessions end after
  152. `session_idle_ttl_secs` (30 minutes by default).
  153. 2. To allow more, raise `max_sessions` in mcp-server's configuration and restart it.
  154. If the 503 says mcp-server runs `interface_only`, its configuration is the one used to
  155. collect its interface, not to serve: remove `interface_only` and restart it.
  156. ### The address is an engine WebSocket address
  157. `mcp_url` (or `III_PLUGIN_MCP_URL`, or `--url`) is a `ws://` address: the engine's, not
  158. mcp-server's. Use mcp-server's HTTP address, `http://127.0.0.1:3111/mcp` by default (see
  159. [Install the plugin](#install-the-plugin)).
  160. ### A call is forbidden
  161. The error says `FORBIDDEN`: rbac-proxy does not let agents call that function.
  162. 1. If agents should call it, add it to rbac-proxy's `expose_functions` (for example
  163. `match("orders::*")`) and make sure it is not in `forbidden_functions` (step 2 of
  164. [Set up iii to serve it](#set-up-iii-to-serve-it)).
  165. 2. Restart rbac-proxy, then mcp-server, so the rules apply to its connection:
  166. `iii call compose::restart container=rbac-proxy`, then `container=mcp-server`.
  167. `secrets::resolve` is forbidden on purpose: it would let agents read every secret.
  168. ### The iii tools are missing in Claude Code
  169. 1. Run `/mcp` in Claude Code. If there is no `iii` server, check the plugin is installed
  170. and enabled: `claude plugin list` (see [Install the plugin](#install-the-plugin)).
  171. 2. If the `iii` server is there but failed, mcp-server is not answering: follow
  172. [mcp-server is not reachable](#mcp-server-is-not-reachable).
  173. 3. After a fix, run `/mcp` and reconnect, or start a new session.
  174. ### The default-mcp profile did not load
  175. The session started without the `default-mcp` profile, though mcp-server answered.
  176. 1. Check `iii-directory` is `ready` in `iii call compose::status`; it serves the profiles.
  177. 2. Check rbac-proxy exposes the profile functions to agents (`expose_functions`), then
  178. restart rbac-proxy and mcp-server.
  179. 3. Start a new Claude Code session.
  180. ### Node is missing or too old
  181. The plugin's hooks run `node`: Claude Code shows them failing at session start when Node
  182. is missing or older than 22. Install Node 22 or later and start a new session.
  183. ## Development
  184. ```sh
  185. pnpm install
  186. pnpm run build # bundle src/ into plugins/iii/cli/index.mjs + BUILD.json
  187. pnpm test # vitest
  188. pnpm run lint && pnpm run typecheck
  189. pnpm run check:committed-build # the committed CLI matches its sources
  190. claude plugin validate . && claude plugin validate plugins/iii
  191. ```
  192. `src/` holds the plugin's command line and the modules the `claude-code` worker shares with
  193. it (`commands.ts`, `directory.ts`, `mcp.ts`, `session.ts`, `mode.ts`); the worker fetches
  194. the latest `main` of this repository when it is built.
  195. `plugins/iii/cli/index.mjs` is committed: a marketplace install is a git copy with no build
  196. step. After changing `src/` or `scripts/build.mjs`, run `pnpm run build` and commit both
  197. `cli/index.mjs` and `cli/BUILD.json`; CI fails when they are stale or edited by hand.
  198. ## License
  199. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.