Skip to content

Safety Model

An assistant with tools can do real damage if the tools are careless. The FHIR Frog MCP server is built so that the dangerous things are visible and need your approval, and so that the worst a confused assistant can do is limited.

Plan first, then confirm

Any tool that starts or stops a container, writes a configuration file, overwrites files in your workspace, or can write to a shared server needs confirm: true. Without it the tool does nothing and returns a needs_confirmation error whose details.plan lists exactly what it would do:

frog_server_register(name: "qld-ereferral", url: "https://example.org/fhir", spec: "au-core")
  -> needs_confirmation
     plan: Create ~/.fhir-frog/backends.yaml
           name: qld-ereferral, url: https://example.org/fhir, spec: au-core, clientSecret: [not shown]

A well-behaved assistant shows you that plan and repeats the call with confirm: true only after you agree. If your assistant confirms without showing you, tell it to stop doing that; the skill instructs it not to.

Running tests can write to a server

A TestScript that creates a Patient writes to the server under test. So frog_run_local and frog_run_remote need confirm: true when the target is a non-loopback URL, unless it is a backend you registered as managed: true (the local test server the MCP starts for you is one). Loopback addresses (localhost, 127.0.0.1, ::1) are recognised strictly: 127.0.0.1.evil.example is not loopback.

Secrets never travel through the assistant

  • Credentials are not accepted as plain values. clientSecret must be a reference to an environment variable, written ${FROG_SECRET}. A literal value is refused with secret_not_allowed, and the secret never appears in the tool call, the transcript or the config file.
  • The MCP resolves the variable when it runs and redacts anything resolved from a secret reference in results, logs and error messages.
  • frog_server_describe and frog_server_list show that a backend is authenticated, never the values.

Set the variable in the environment that starts the MCP (your shell, or the env block of the client configuration), not in the chat.

Files stay in the workspace

All reads and writes of user files are confined to one workspace root, taken from FROG_WORKSPACE. Paths that escape it (.., absolute paths elsewhere, symlinks pointing out) are refused with path_outside_workspace. The root itself must not be / or your home directory. Scaffolding never overwrites an existing file without confirm: true.

Containers are fenced

  • Only images on an allowlist can be started: the frog-runner image from the FHIR Frog registry and the stock HAPI image. Ports are limited to 1024–65535.
  • Containers the MCP creates carry the label frog.mcp=1. Stop tools only touch labelled containers and networks; a container of the same name that you started yourself is reported as name_conflict and left alone.
  • Published ports bind to 127.0.0.1 only. The local server and runner are not reachable from the network.
  • When the MCP itself runs in a container it needs your Docker socket, which is equivalent to root on the host. Use the container image only on a machine where you accept that; see Install.

What the MCP will never do

  • Push to git remotes, publish packages or contact services other than the FHIR servers, registries and package servers you point it at.
  • Store, log or echo a secret value.
  • Follow an HTTP redirect when checking a server (a redirect is reported, not followed).
  • Run an unbounded call: every tool returns within about two minutes; long operations report starting and you poll.
  • Start anything outside the allowlist, or act on a container it did not create.

Limits to be aware of

  • Reset policies on backends (resetPolicy) are recorded but not executed in v0.1: the MCP will not clean a shared server for you.
  • Fixtures declared with autodelete delete by fixture file id, so created resources can leak; see the troubleshooting page. Prefer a fresh local server for repeatable runs.
  • confirm: true is a prompt to you, not a security boundary against the assistant: review the plan.