@auditswarms/mcp-bridge

🌉 STDIO-to-HTTP bridge for connecting Claude Desktop to AuditSwarms MCP server on GCP.

What is this?

Claude Desktop uses STDIO transport (standard input/output) for MCP servers, but can't connect directly to remote HTTP servers. This tiny bridge proxy forwards STDIO messages from Claude Desktop to your AuditSwarms MCP server running on Google Cloud Platform.

No installation required - just use npx!

Quick Start

1. Get Your OAuth Token

Visit your AuditSwarms deployment:

https://auditswarms-app-997439271657.us-central1.run.app/oauth-setup

Click "Generate OAuth Token" and copy the token.

2. Configure Claude Desktop

Open Claude Desktop settings and add this MCP server configuration:

macOS/Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "auditswarms": {
      "command": "npx",
      "args": ["-y", "@auditswarms/mcp-bridge"],
      "env": {
        "MCP_REMOTE_URL": "https://auditswarms-mcp-997439271657.us-central1.run.app/mcp",
        "MCP_TOKEN": "your-token-here"
      }
    }
  }
}

3. Restart Claude Desktop

That's it! Claude will now be able to access your AuditSwarms data.

Environment Variables

• MCP_REMOTE_URL (required) - Your GCP MCP server URL
• MCP_TOKEN (required) - OAuth token from /oauth-setup
• MCP_DEBUG (optional) - Set to true to see debug logs

How It Works

Claude Desktop (STDIO) → Bridge (This Package) → GCP MCP Server (HTTP)
                ↓                                        ↓
          User's Computer                        Google Cloud Run

1. Claude Desktop sends JSON-RPC messages via STDIO
2. Bridge converts to HTTP POST requests
3. Forwards to your GCP MCP server with OAuth token
4. Returns responses back through STDIO
5. Claude Desktop receives the data

Features

• ✅ Zero installation (uses npx)
• ✅ Automatic JSON-RPC 2.0 validation
• ✅ Secure OAuth token authentication
• ✅ Error handling and helpful messages
• ✅ Optional debug logging
• ✅ Works on Windows, macOS, and Linux

Troubleshooting

"MCP_REMOTE_URL environment variable is required"

Make sure you've added the env section to your Claude Desktop config with the correct MCP server URL.

"MCP_TOKEN environment variable is required"

Visit /oauth-setup to generate a new token and add it to your Claude Desktop config.

Token expired

Tokens are valid for 30 days. Generate a new token at /oauth-setup when the old one expires.

Connection errors

Check that:

1. Your GCP MCP server is running
2. The URL is correct
3. Your token hasn't expired
4. You have internet connection

Advanced Usage

Custom Token Expiry

Tokens default to 30 days. To create longer-lived tokens, use the API directly or contact your admin.

Debug Mode

Enable debug logging to see all requests/responses:

{
  "mcpServers": {
    "auditswarms": {
      "command": "npx",
      "args": ["-y", "@auditswarms/mcp-bridge"],
      "env": {
        "MCP_REMOTE_URL": "https://auditswarms-mcp-997439271657.us-central1.run.app/mcp",
        "MCP_TOKEN": "your-token-here",
        "MCP_DEBUG": "true"
      }
    }
  }
}

Debug logs appear in Claude Desktop's developer console.

Using with Custom Domains

If you've set up a custom domain for your AuditSwarms deployment, update the URLs:

{
  "env": {
    "MCP_REMOTE_URL": "https://mcp.yourdomain.com/mcp",
    "MCP_TOKEN": "your-token-here"
  }
}

Security

• OAuth tokens are transmitted via HTTPS only
• Tokens are scoped to specific user permissions
• Tokens automatically expire after 30 days
• No credentials are stored by the bridge
• All data stays between your computer and your GCP server

Requirements

• Node.js 18+ (automatically installed by npx)
• Claude Desktop 0.5.0+
• Active AuditSwarms deployment on GCP

Alternative: Local Development

For local development, you can run the bridge directly:

git clone https://github.com/your-org/AuditSwarm-GCP.git
cd AuditSwarm-GCP
npm install

# Set environment variables
export MCP_REMOTE_URL="https://your-mcp-server.run.app/mcp"
export MCP_TOKEN="your-token-here"

# Run bridge
npm run mcp:bridge

Then configure Claude Desktop to use the local bridge:

{
  "mcpServers": {
    "auditswarms": {
      "command": "npm",
      "args": ["run", "mcp:bridge"],
      "cwd": "/absolute/path/to/AuditSwarm-GCP"
    }
  }
}

Support

• 📖 Full Documentation
• 🐛 Report Issues
• 💬 Get Help

License

MIT © AuditSwarms

Made with ❤️ by the AuditSwarms team