Archive MCP Server

An MCP server that exposes the Enterprise Data Archival & Records Management System's records and retention logic to any MCP client — Claude Code, Claude Desktop, Cursor, or your own client — over stdio.

Instead of clicking through the React dashboard to answer "what can we archive in Finance?", you ask the model, and it calls these tools.

Tools

Related MCP server: EndpointRead-MCP

Resources

Requirements

Python 3.10+ and MCP SDK 2.x. The v2 SDK renamed FastMCP to MCPServer and moved it to mcp.server.mcpserver; this code targets v2. Data access is SQLAlchemy 2.x, with psycopg2 for PostgreSQL.

Setup

python -m venv .venv
source .venv/bin/activate          # macOS/Linux
.venv\Scripts\activate             # Windows

python -m pip install -r requirements.txt
python seed_db.py                  # builds the local demo database
python server.py --selftest        # sanity check, no MCP client needed

Then verify it over a real MCP session:

python verify_mcp.py

Choosing a database

The server reads DATABASE_URL (from the environment, or from a .env file — see .env.example):

archive.db holds synthetic records, so the server — and --selftest — run for anyone who clones this repo without credentials. It is not a different codebase: seed_db.py builds the same five-table schema the production database uses (active_records, archived_records, retention_policy, audit_logs, documents), so every query in server.py runs unchanged against either one.

Never commit a real DATABASE_URL. .env is gitignored; .env.example is the committed template.

Connecting to Claude Code

From the project directory:

claude mcp add --scope project archive-system -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py
claude mcp list

--scope project writes a committable .mcp.json at the project root, so anyone who clones the repo gets the server. Start claude, approve the project server when prompted, and check /mcp — archive-system should show Connected with 6 tools. Then ask:

Which IT department records are overdue for archival?

If it fails to start, run claude --debug=mcp and read the log under ~/.claude/debug/.

Connecting to Claude Desktop

Add this to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "archive-system": {
      "command": "D:\\Python\\project\\archive-mcp\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Python\\project\\archive-mcp\\server.py"]
    }
  }
}

Point command at the venv's Python, not bare python — the host does not inherit your shell's PATH or your activated virtualenv. On Windows both paths need doubled backslashes.

Restart from the tray icon — Quit, not the window close button — or the app keeps running with the old config.

Note for the Microsoft Store (MSIX) build on Windows: its config is not under %APPDATA% but under the package's own directory, %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\. It launches local stdio servers normally. Don't try to confirm that from logs\mcp.log — that file can sit empty and untouched while everything works. Check for the process instead; the server runs as a child of Claude Desktop:

Get-CimInstance Win32_Process -Filter "Name like '%python%'" |
  Where-Object { $_.CommandLine -like "*archive-mcp*" }

Design notes

• stdio transport, because the client launches the server as a subprocess on the same machine. An HTTP transport would make sense if the server ran remotely and served several clients.

• One seam for storage. _connect() returns a SQLAlchemy Engine and is the only place that knows what the database is. Queries use named bind parameters (:department), which are dialect-neutral, so SQLite and PostgreSQL share one query set rather than two.

• pool_pre_ping=True, because a serverless PostgreSQL (Neon and friends) suspends idle compute and an MCP server sits idle between questions. Without it, the first question after a quiet spell fails on a stale pooled connection.

• Eligibility is computed in Python, not SQL. PostgreSQL INTERVAL arithmetic has no SQLite equivalent, and keeping the comparison in one place keeps the two backends honest. At a few thousand active rows the cost is not worth optimising away.

• Age is measured from joining_date. created_at is the bulk-load timestamp and is identical for every row, so retention computed from it would find nothing eligible, ever. joining_date is an employee-level date standing in for a document date — the schema carries no document date, which is a real gap worth closing upstream.

• Archival state is a table, not a flag. A record lives in active_records or in archived_records, and ids are stable across the move, so get_record checks both. The status column is employment status and is unrelated.

• Tools are annotated read-only. Each carries ToolAnnotations(read_only_hint=True, destructive_hint=False), so a client can tell a safe call from a state-changing one before it runs.

• Tools are read-only in fact, too. Archiving is destructive and policy-governed; archival_candidates deliberately reports what could be archived and leaves the decision to the existing scheduled job. Exposing a destructive tool to a model is a choice that needs a confirmation path first.

• Docstrings are the API. The model picks tools from the docstring and type hints, so the valid departments and document types are enumerated there. A stale enum is worse than none: the model passes a plausible-looking value like Legal, gets an empty result, and reports that there is nothing to archive.

• One definition of "eligible", used in both directions. _verdict ages a record against its retention period; _eligible_on inverts it to give the date a record crosses that period, which is what retention_forecast buckets by. They must agree exactly, or a record can appear as upcoming in the forecast and overdue in archival_candidates on the same day. Writing the inverse the obvious way (joining + timedelta(days=years * 365.25)) breaks this, because date + timedelta keeps only whole days and silently drops the .75.

• Output is formatted text, not raw JSON dumps, so the model can quote it back to a user without reformatting.