Skip to main content

MCP Documents

An MCP document is the artifact that tells the Appilots agent what your app looks like: which screens exist, how they're connected, and what forms and actions live on each one. It's generated locally by the CLI from your app's source code, then uploaded to your project so the agent has something to reason against.

What's in it​

At a high level, an MCP document describes:

  • Screens — one entry per screen the CLI could identify, including its registered fields, actions, and any suggested prompts.
  • Navigation — the graph of how screens connect (including nested navigators), so the agent can plan multi-step routes.
  • Metadata — generation info such as the document version and counts used for sanity-checking a sync.

The CLI builds this from two sources: static analysis of your JSX/navigation code, and runtime registration hints your app already declares through registerScreen() calls and JSDoc annotations (things like effect, riskLevel, and requiresConfirmation on an action). See CLI output format for the exact document shape, and CLI usage for how to run the generator.

Generating and syncing​

You generate and upload the document with the CLI:

appilots sync

appilots sync analyzes your app, builds the MCP document, and uploads it to the project identified by your API key. Appilots keeps exactly one active document per project — the document currently used to answer chat requests.

To avoid uploading the same document twice, the CLI computes a content checksum of the generated document before syncing. If that checksum matches the currently active document on the server, the sync is reported as unchanged and nothing new is stored. If it differs, the server stores the new document, marks it active, and deactivates the previous one. This makes appilots sync safe to run on every CI build — a no-op sync is cheap.

The document also carries a version, a plain string field (defaults to 1.0) that you or your build controls. Unlike the checksum, this isn't computed automatically — bump it as part of your own release process if you want a human-readable marker of which document generation is active.

Why staleness matters​

The MCP document describes a specific build of your app. If you ship a new screen, rename a field, or change a form, but forget to re-run appilots sync, the agent keeps reasoning against the old document — it may try to navigate to a screen that moved, or fill a field that no longer exists.

To help catch this, the SDK can report the running app's version and the MCP document version it was built with (appVersion / mcpVersion in AppilotsConfig). This lets Appilots flag drift between what a client claims to be running and what document is actually active for the project, which is especially useful if you ship multiple app versions at once (e.g. a staged rollout). Treat a stale document as a build hygiene problem: the fix is always to re-run appilots sync, ideally as a required step in CI. See CI integration for wiring this into your pipeline.

Last updated on