Foundry Rest Api Mcp Server — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Foundry Rest Api Mcp Server (Agent Skill) and scored it 45/100 (orange). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 2 high-severity and 2 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 4 flagged
A base64 string of 128+ characters appears in a documentation file. Encoded prompt injection hides the hostile instruction in base64 — invisible to keyword filters — and relies on the agent's ability to decode it at runtime. There is no normal authoring reason to embed a multi-hundred-byte base64 blob in skill docs.
*.sig, SIGNATURES) outside the documentation.A base64 string of 128+ characters appears in a documentation file. Encoded prompt injection hides the hostile instruction in base64 — invisible to keyword filters — and relies on the agent's ability to decode it at runtime. There is no normal authoring reason to embed a multi-hundred-byte base64 blob in skill docs.
*.sig, SIGNATURES) outside the documentation.The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
An MCP (Model Context Protocol) server that wraps the ThreeHats Foundry VTT REST API relay, so an LLM agent (Claude Code / Claude Desktop) can author and manage Foundry VTT content — primarily creating D&D 5e creatures — through native MCP tools instead of raw HTTP calls.
Status: V1 implemented. The stdio MCP server lives undersrc/with unit tests undertest/. See [Install & configure](#install--configure) below to run it. The original plan that drove the build is inIMPLEMENTATION_PLAN.md.
The relay (github.com/ThreeHats/foundryvtt-rest-api-relay, public host https://foundryrestapi.com) bridges a running Foundry world to a REST API over a WebSocket. A Foundry-side module connects out to the relay; external clients then call REST endpoints, authenticating with an x-api-key header and targeting a world via a clientId query param.
This MCP server is a thin, typed client of that relay. It does not talk to Foundry directly and requires no Foundry-side code of its own (the relay's module handles that). That is the key differentiator from existing Foundry MCP servers, which all ship a custom Foundry module + socket (see IMPLEMENTATION_PLAN.md § Prior Art).
v1 implements the relay's document-authoring surface — these five scopes only:
| Scope | Endpoints | Capability |
|---|---|---|
clients:read | GET /clients | Discover connected worlds → pick clientId |
search | GET /search | Find actors/items/etc. by name (world + compendiums) |
entity:read | GET /get | Read any document (by UUID or current selection) |
entity:write | POST /create, PUT /update, DELETE /delete, /give, /remove, /increase, /decrease, /kill | Create / update / delete documents; tweak actor inventory & attributes |
structure:write | POST /create-folder, DELETE /delete-folder | Organize content into folders |
This delivers the headline use case end-to-end: build a dnd5e NPC/monster (abilities, HP, AC, CR, traits, embedded attacks) as a real Foundry actor, search/read existing creatures to clone-and-tweak, and file everything into folders.
Everything else in the relay (dice rolls, chat, encounters/combat, scenes, canvas/tokens, effects, files, users, macro execution, streaming events) is out of v1 scope and documented as clearly-marked Future Phases — each unlocks by adding one scope and one tool module.
Optional companion: adding `structure:read` (GET /structure,GET /get-folder) would let us find existing folders, not just create them. Cheap and read-only; deferred for now.
@modelcontextprotocol/sdk@^1.29 (the shipped 1.x line). The renamed V2 SDK (@modelcontextprotocol/server) is not stable until ~mid-2026; migration later is mechanical. Build on 1.x now.fetch (no axios).zod (peer of the SDK).tsup → single npx-runnable bin.FOUNDRY_API_KEY (the x-api-key), FOUNDRY_RELAY_URL (default https://foundryrestapi.com), FOUNDRY_CLIENT_ID (optional; auto-resolves if one world is online), FOUNDRY_USER_ID (optional; omit = GM-level).npm install
npm run build # → dist/index.js (executable, #!/usr/bin/env node)
npm test # unit tests (mocked fetch)
npm run inspect # launch the MCP Inspector against dist/index.js| Var | Required | Default | Purpose |
|---|---|---|---|
FOUNDRY_API_KEY | yes | — | Sent as the x-api-key header. Must include all five v1 scopes (see below). |
FOUNDRY_RELAY_URL | no | https://foundryrestapi.com | Relay base URL. Set to http://localhost:3010 for a self-hosted relay. |
FOUNDRY_CLIENT_ID | no | auto-resolves | Which connected world to target. Auto-resolves when exactly one world is online. |
FOUNDRY_USER_ID | no | GM-level | Scope actions to a Foundry user's permissions. Omit for GM access. |
On startup the server logs the online world(s) to stderr and disables foundry_create_creature if the active world's system isn't dnd5e.
foundry_list_worlds · foundry_search · foundry_get_entity · foundry_create_entity · foundry_update_entity · foundry_delete_entity · foundry_modify_actor · foundry_create_creature · foundry_manage_folder
.mcp.json)Add to .mcp.json in your project root (or via claude mcp add):
{
"mcpServers": {
"foundry": {
"command": "node",
"args": ["/absolute/path/to/foundry-rest-api-mcp-server/dist/index.js"],
"env": {
"FOUNDRY_API_KEY": "your-scoped-key",
"FOUNDRY_CLIENT_ID": "fvtt_8bfa06d76c0c1ac5"
}
}
}
}claude_desktop_config.json)~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"foundry": {
"command": "node",
"args": ["/absolute/path/to/foundry-rest-api-mcp-server/dist/index.js"],
"env": {
"FOUNDRY_API_KEY": "your-scoped-key",
"FOUNDRY_CLIENT_ID": "fvtt_8bfa06d76c0c1ac5"
}
}
}
}Once published to npm, replace"command": "node", "args": ["…/dist/index.js"]with"command": "npx", "args": ["-y", "foundry-rest-api-mcp-server"].
A gated end-to-end test creates then deletes a throwaway JournalEntry against the real relay:
FOUNDRY_LIVE_TEST=1 FOUNDRY_API_KEY=... FOUNDRY_CLIENT_ID=... npm testIMPLEMENTATION_PLAN.md top to bottom. Work the phases in order; each step lists its goal, the files it touches, the exact work, and an acceptance check.EXECUTION_STRATEGY.md for how to run the build — recommended model/effort per ticket, the sequential-foundation → parallel-fan-out → sequential-convergence order, and the branch-per-work-stream (trunk-based) strategy with worktrees + CI gates.API_SPEC.md as the authoritative endpoint reference (request/response shapes, scopes, quirks, the dnd5e NPC schema notes).V1 — Content Authoring). Each issue carries goal, endpoint+scope, file paths, acceptance criteria, and Depends on #N.reference/ folder holds the relay's own docs/examples, mirrored verbatim from the upstream MIT-licensed repo for offline ground-truth (attribution in reference/SOURCE.md; regenerate with scripts/fetch-reference.sh). Filenames mirror their repo paths (e.g. docs_md_api_entity.md, docs_examples_dnd5e-examples.json).decisions/ — architecture & management decisions as ADRs, numbered NNNN-*.md. Each captures one decision (status · context · decision · consequences) and is immutable once Accepted; a later ADR supersedes an earlier one by reference, so history is never edited in place. Index + convention: decisions/README.md.specs/ — technical component specs, numbered NNNN-*.md — the internal contracts the code implements (relay client, tool surface, dnd5e NPC builder). Index: specs/README.md.The top-level docs (IMPLEMENTATION_PLAN.md, EXECUTION_STRATEGY.md, API_SPEC.md) are the elaborated references; the ADRs are the atomic, supersede-able record of why.
A read-only key returns 403 API key lacks required scope: entity:write. You cannot add scopes to an existing key value — mint a new one that includes all five v1 scopes:
https://foundryrestapi.com → API Keys → Create Scoped Key → tick clients:read, search, entity:read, entity:write, structure:write → copy the key (shown once).POST /auth/key-request with {"appName":"foundry-mcp","scopes":["clients:read","search","entity:read","entity:write","structure:write"]} → open the returned approvalUrl → poll GET /auth/key-request/:code/status until approved (the response then includes apiKey).The known target world for this project is "Wilds Beyond the Witchlight", clientId fvtt_8bfa06d76c0c1ac5 (dnd5e 5.2.2, Foundry v13.351).
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.