MCP Integration

What MCP Integration Provides

VersionForge exposes an MCP (Model Context Protocol) server that lets AI assistants -- Claude, and other MCP-compatible clients -- query your sync infrastructure conversationally. Instead of navigating dashboards or writing API calls, you ask questions in natural language and get structured answers.

Example queries you can run through an MCP-connected assistant:

• "What was the last sync status for the Workday connector?"
• "Show me the diff for run #1847."
• "Are there any failed cross-checks this week?"
• "Which connections are currently degraded?"
• "How many rows were loaded in yesterday's NetSuite GL sync?"

The MCP server is read-only by default. It exposes sync status, run history, connection health, and validation results -- but it does not trigger syncs or modify data unless you explicitly enable write scopes.

Setting Up the MCP Server

1. Enable the MCP server

   Navigate to Settings > Integrations > MCP Server and toggle the server to Enabled. The MCP server starts alongside the main VersionForge application on a dedicated port (default: 3001).

2. Generate an MCP access token

   Click Generate Token to create a token scoped to MCP access. You can choose between two scopes:

   • read-only -- Query sync status, run history, and connection health. No write operations.
   • read-write -- All read capabilities plus the ability to trigger syncs and approve Safety Gate items via the assistant.

   Copy the token. You will need it when configuring your AI assistant.

3. Configure your AI assistant

   In your MCP-compatible client, add VersionForge as a server. The configuration format depends on your client, but the essential fields are:

   {
     "mcpServers": {
       "versionforge": {
         "url": "https://your-instance.versionforge.com:3001/mcp",
         "token": "vf_mcp_your_token_here"
       }
     }
   }
   

   For Claude Desktop, add this block to your claude_desktop_config.json file. For other MCP clients, consult their documentation for server configuration.

4. Test the connection

   Ask your AI assistant: "What connections are configured in VersionForge?" If the MCP server is running and the token is valid, you will see a list of your configured source and target connections with their current health status.

Available MCP Resources

The MCP server exposes the following resources:

| Resource | Description | Example Query | |----------|-------------|---------------| | Connections | List all connections with health status | "Which connections are healthy?" | | Sync Runs | Query run history with filters (date, status, connector) | "Show me failed runs in the last 7 days" | | Run Detail | Detailed view of a specific run: stages, row counts, timing | "What happened in run #1847?" | | Diffs | Row-level change detail for a specific run | "Show me the adds from the last Workday sync" | | Cross-Checks | Validation results and variance detail | "Did the last NetSuite sync pass cross-check?" | | Safety Gate | Current review queue status and pending items | "How many rows are waiting for review?" |

MCP Server Architecture

The MCP server runs as a lightweight sidecar process alongside the main VersionForge application. It connects to the same database and reads from the same data layer, so query results are always current. The server does not cache responses -- every query returns live data.

Security Considerations

• The MCP server requires HTTPS in production. HTTP connections are rejected unless you explicitly enable them for local development.
• Tokens are revocable at any time from Settings > Integrations > MCP Server > Active Tokens.
• All MCP queries are logged in the audit trail with the token identity, timestamp, and resource accessed.
• The MCP server does not expose credentials, secrets, or raw API keys from your connections. It only exposes operational metadata.