Stateark

What the stateark MCP server does

The stateark MCP server preserves the working state of an AI-assisted project between chats. Instead of retaining only a conversational summary, it stores decisions, requirements, constraints, relevant rejected approaches, open questions, and the files associated with a project. A savepoint creates a new version under the local StateArk directory, and a later resume loads the latest state into a new chat.

Savepoints are ordinary folders rather than a proprietary database. They include Markdown and JSON state files, metadata, a SHA-256 artifact manifest, journals, and the project files themselves. The local directory remains the source of truth, so the saved material stays usable in an editor even if the agent is no longer installed.

How it works

The local agent binds to 127.0.0.1 by default and exposes an MCP endpoint, an upload page, and a health endpoint. On first startup, it creates a random access key in the StateArk root. The MCP client uses the endpoint and key to communicate with the agent.

The main chat workflows are Savepoint, Resume, History, and Diff. Files omitted from a later savepoint can be carried forward with their original hash. StateArk also checks for likely incomplete transfers, including truncation markers, unexpectedly smaller files, described-but-missing files, and unchanged savepoints. These checks produce warnings without preventing a savepoint from being written.

A journal records turning points between savepoints for projects that already have a saved version. Writes are serialized across processes, allowing multiple agents on one machine to work against the same project store. A crashed process releases its lock automatically.

Setup and configuration

The simplest installation requires Node 20 or newer. Run npx stateark, then fully quit and reopen Claude Desktop. Source installation is also available through npm installation, the build step, and the setup script. npx stateark remove unregisters the service without deleting saved projects.

Local-only operation needs no .env file. The default store is ~/StateArk; STATEARK_LOCAL_ROOT can change it. Lock timing and file-system retry behavior can be adjusted with STATEARK_LOCK_WAIT_MS, STATEARK_LOCK_STALE_MS, and STATEARK_FS_RETRIES.

Optional Supabase mirroring requires the listed database migrations and SUPABASE_URL, SUPABASE_SECRET_KEY, STATEARK_OWNER_ID, and STATEARK_STORAGE_BUCKET. Local data is committed before a cloud push, and failed pushes can be retried with sync_savepoint. The mirror is not end-to-end encrypted.

Tools and capabilities

The stateark MCP server supports these project operations:

• Save a new version of the current project state.
• Resume the latest version in a fresh chat.
• List project versions with History.
• Compare savepoints with Diff.
• Retry a failed Supabase mirror operation with sync_savepoint.
• Preserve artifacts and verify their recorded SHA-256 hashes.
• Record and consolidate journal entries.

Limitations and notes

StateArk is designed for local MCP clients. Claude Desktop, Claude Code, and similar local hosts can reach the default agent, but hosted Claude, ChatGPT, and Gemini web clients generally cannot connect to localhost. Remote access is not currently available; using an HTTPS route requires securing the access key, allowed hosts, and reverse proxy.

Multiple machines writing the same synced folder at once can create conflicts that Dropbox, OneDrive, or iCloud must resolve. The optional Supabase mirror is a hosted copy that can read stored content, not an end-to-end encrypted backup. The project is licensed under Elastic License 2.0, which does not allow offering it as a hosted or managed service to third parties.