MCP & Agent Development

The Envault MCP Server (mcp-server/) acts as a bridge between AI assistants (like Claude Desktop, Cursor, and RooCode) and the Envault backend.

This document outlines how to set up, test, and maintain the MCP server infrastructure locally.

Current Auth Model (Important)

Default local agent setup no longer relies on long-lived standalone MCP web tokens.

• envault mcp install now fetches a delegated project-scoped JWT (envault_agt_).
• Delegated tokens are short-lived (1 hour) and scoped to one project.
• Mutation calls remain gated by HITL approval.

Manual standalone token configuration is now a fallback path for isolated environments where CLI-managed install is unavailable.

Development Setup

The MCP server is a standalone Node.js package located in ./mcp-server. To develop locally:

1. Navigate to the directory and install dependencies:

   cd mcp-server

   npm install

2. Build the server:

   npm run build

3. To test your local build with an MCP client, you can modify your client's configuration to point to your local executable instead of the published npm package:

   {
     "server": {
       "envault-dev": {
         "command": "node",
         "args": ["/absolute/path/to/Envault/mcp-server/server.mjs"],
         "env": {
           "ENVAULT_TOKEN": "<YOUR_DEV_TOKEN>",
           "ENVAULT_BASE_URL": "http://localhost:3000"
         }
       }
     }
   }

CLI-Managed Local Setup (Preferred)

For end-to-end local validation of the production path:

envault init
envault login
envault mcp install --local

This exercises delegated token issuance and config injection used by real user flows.

MCP Token Cleanup Automation

Standalone MCP web tokens are automatically cleaned up through a protected cron endpoint. When testing that fallback mode locally in an authorized environment, ensure this cron job is configured.

• Endpoint: /api/cron/mcp-token-cleanup
• Auth: Authorization: Bearer <CRON_SECRET>
• Database: Supabase pg_cron

Setting up the Cron Job

1. Ensure CRON_SECRET is set in your .env.local and production environments.
2. Schedule the job in the Supabase SQL Editor by executing the following scripts in order:
   • supabase/migrations/20260405000000_add_mcp_web_token_columns_to_profiles.sql
   • scripts/setup-mcp-token-cleanup-cron.sql

Note: The cron SQL file safely unschedules legacy hourly cleanup routines before creating the daily schedule.

Local Validation Checklist

Before merging MCP-related PRs, execute this local validation checklist:

1. Validate delegated auth path: Run envault mcp install --local in a linked project and confirm generated config contains ENVAULT_TOKEN=envault_agt_... and valid base URL.
2. Validate delegated token behavior: Run a read operation from MCP client (status/context) and confirm project scoping.
3. Validate HITL mutation path: Trigger a mutation via MCP tool and confirm a 202 Accepted + approval link flow.
4. Fallback token coverage (optional): Generate a standalone MCP token from dashboard (Settings -> Security) and validate parsing against CLI-protected route:

   curl -k -i \
     -H "Authorization: Bearer <FULL_MCP_TOKEN>" \
     "http://localhost:3000/api/cli/me"

5. Fallback cleanup: Force-expire standalone token directly in database, then trigger cleanup manually:

   curl -k -i \
     -H "Authorization: Bearer <CRON_SECRET>" \
     "http://localhost:3000/api/cron/mcp-token-cleanup"

6. Verify deletion: Confirm fallback token is invalid and MCP profile token fields are cleared.

HITL (Human-in-the-Loop) Interceptor Testing

Testing the MCP server interaction is crucial because it handles AI-driven modifications to secrets. The mcp-agent interceptor enforces human approvals.

Run the integration tests to exercise token cleanup, lifecycle events, and the HITL approval endpoints:

npx vitest tests/mcp-token-lifecycle.test.ts

npx vitest tests/agent-interceptor.test.ts