Wiki Navigation

Server State and Isolation (Important for Consultants)

MCP Engine stores server-side state (by default under ~/.mcp-engine/), including preferences, policy rules, tests, model change history, audit logs, and license state. This matters because multiple clients on the same machine share this state - and that can cause real problems if you're not aware of it.

What goes wrong in practice

Here are the concrete scenarios that catch people off guard:

  • Cross-customer bleed - you finish an engagement with Customer A, then start working with Customer B on the same laptop. Your naming conventions, guardrails, policy rules, and test definitions from Customer A are still active. The assistant starts applying Customer A's conventions to Customer B's model.
  • Claude Desktop vs Claude Code disagree - you activate a Pro license in Claude Desktop but Claude Code shows Free tier. They are pointing at different MCP Engine instances (different ports, different OS users, or different config paths). The fix: check license file path in both and make sure they point to the same server.
  • "Where did my export go?" - you asked the assistant to save test results to a file. It saved them on the machine running the MCP server. If that server runs in a container or on a remote host, the file is there, not on your laptop.
  • Tests from a previous session still running - you defined regression tests for Model A. You switch to Model B but the old test definitions are still there because tests are stored per-server, not per-model.

How to keep things clean

If you work across multiple customers or environments:

  • Use a separate OS user per customer/environment - each user gets its own ~/.mcp-engine/ directory with completely isolated state.
  • Or configure separate storage directories - set MCP_ENGINE_PREFERENCES_DIR, MCP_ENGINE_POLICIES_DIR, MCP_ENGINE_TESTS_DIR per environment.
  • Export and reset between engagements - export your preferences baseline, then reset preferences before starting with a new customer.

See also