Varig Service MCP Bridge

A Model Context Protocol (MCP) bridge that provides user-authenticated access to the Varig GraphQL backend via Auth0.

Overview

This module acts as a stdio-to-SSE bridge for MCP clients. It handles:

• Deferred authentication — starts immediately without blocking on login
• LLM-triggered login — login and status tools the LLM can call to authenticate
• Persistent SSE connection to the Varig backend
• Automatic token refresh in the background
• JSON-RPC bridging between MCP clients (stdin/stdout) and the backend (SSE)

Requirements

• Node.js 20 or higher
• Auth0 account configured with the appropriate audience and client ID

Installation

npm install -g @varig-technologies/varig-service-mcp-bridge

Or run directly with npx:

npx @varig-technologies/varig-service-mcp-bridge

Usage

In MCP Client Configuration

Add this bridge to your MCP client's configuration (e.g., Claude Desktop, Cursor, Windsurf):

{
  "mcpServers": {
    "varig": {
      "command": "npx",
      "args": ["-y", "@varig-technologies/varig-service-mcp-bridge"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "varig": {
      "command": "varig-service-mcp-bridge"
    }
  }
}

Authentication Flow

The bridge supports deferred authentication — it starts immediately and handles MCP protocol handshakes without requiring prior authentication.

Two operating modes:

1. Unauthenticated mode (startup with no valid tokens):

   • Bridge handles MCP protocol directly
   • Only login and status tools are available
   • Call login to trigger browser-based Auth0 login

2. Authenticated mode (valid tokens exist or after successful login):

   • Bridge connects to backend SSE and proxies all tools
   • Bridge-local tools (login, status, uploadFile) are injected
   • Background timer refreshes tokens before expiration

Important: After calling the login tool, you must restart your MCP client for the full list of tools to become available. The bridge attempts to notify the client via the MCP protocol, but many clients require a restart to refresh their tool list.

If tokens expire and cannot be refreshed, the bridge automatically transitions back to unauthenticated mode.

Bridge Tools

| Tool | Description | |------|-------------| | login | Opens a browser for Auth0 login. Returns immediately if already authenticated. | | status | Returns authentication state, token expiry info, and login progress. | | uploadFile | Reads a local file and uploads via GraphQL mutation (file content never enters LLM context). |

File Upload

The bridge provides a local uploadFile tool that reads files from the user's filesystem and POSTs them to the backend — the file content never passes through the LLM's context.

The tool supports GraphQL mutations that use the Upload! scalar (e.g., uploadReportFile, uploadUserFile, uploadProfilePicture, uploadReportConverterFile).

Example

{
  "name": "uploadFile",
  "arguments": {
    "filePath": "/Users/me/Documents/report.xlsx",
    "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "query": "mutation ($file: Upload!) { uploadUserFile(file: $file) { id name } }"
  }
}

For mutations that require additional variables:

{
  "name": "uploadFile",
  "arguments": {
    "filePath": "./data.csv",
    "mimeType": "text/csv",
    "query": "mutation ($file: Upload!, $buildingId: String!) { uploadReportConverterFile(buildingId: $buildingId, file: $file) { id } }",
    "variables": "{\"buildingId\": \"abc123\"}"
  }
}

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | filePath | yes | Absolute or relative path to the file | | mimeType | yes | MIME type of the file | | query | yes | GraphQL mutation document | | fileVariableName | no | GraphQL variable name for the file (default: "file") | | variables | no | JSON string of additional mutation variables |

Configuration

All configuration is optional. Override defaults with environment variables:

| Variable | Default | Description | |----------|---------|-------------| | VARIG_MCP_AUTH0_DOMAIN | varig-as.eu.auth0.com | Auth0 tenant domain | | VARIG_MCP_CLIENT_ID | 2VRKi8r9rIiVIyc7z7Dv4el2I9NcAOul | OAuth client ID (public SPA/native app) | | VARIG_MCP_AUDIENCE | https://varig-as.tech/ | OAuth audience (API identifier) | | VARIG_MCP_BACKEND_URL | https://api.varig.tech | Backend API base URL | | VARIG_MCP_SSE_ENDPOINT | /mcp/sse | SSE endpoint path | | VARIG_MCP_UPLOAD_FILE_ENDPOINT | /mcp/upload-graphql-with-file | File upload endpoint path |

Example: Custom Backend

VARIG_MCP_BACKEND_URL=https://custom-api.varig.tech npx @varig-technologies/varig-service-mcp-bridge

Token Storage

Tokens are stored at:

~/.config/varig-mcp/tokens.json

The token file contains:

• access_token - JWT for API authentication
• refresh_token - For obtaining new access tokens
• expires_at - Token expiration timestamp
• token_type - Usually "Bearer"
• scope - Granted OAuth scopes

Note: This file contains sensitive credentials. Keep it secure and do not commit it to version control.

Development

git clone https://github.com/Varig-Technologies/varig-service.git
cd varig-service/mcp-bridge
npm install
npm start

Run tests:

npm test

Architecture

┌──────────────┐     stdin/stdout    ┌──────────────────┐      SSE/HTTP       ┌──────────────┐
│  MCP Client  │ ◄─────────────────► │  varig-service-  │ ◄─────────────────► │ Varig Backend│
│ (Claude, etc)│     JSON-RPC        │   mcp-bridge     │                     │  + Auth0     │
└──────────────┘                     └──────────────────┘                     └──────────────┘

The bridge:

1. Starts immediately in unauthenticated mode (or authenticated if valid tokens exist)
2. Responds to MCP protocol handshakes (initialize, tools/list) directly
3. Authenticates via OAuth 2.0 + PKCE when the LLM calls login
4. Establishes a persistent SSE connection to the backend
5. Receives JSON-RPC requests from the MCP client via stdin
6. Forwards requests to the backend via HTTP POST
7. Streams responses back to the client via stdout
8. Automatically refreshes tokens in the background

License

MIT

Support

For issues and questions, please open an issue on GitHub.