Skip to main content

Hub Bridge Setup

What is Hub Bridge?​

Hub Bridge is a local proxy that connects clients (like Cursor, VS Code, JetBrains) to Civic. Your client thinks it's talking to a local MCP server, but the bridge handles authentication and forwards requests to your selected Civic servers.

npm package: @civic/hub-bridge

info

Use Hub Bridge when: Your client only supports local/stdio MCP servers and doesn't have remote URL options.

Check Client Compatibility First​

Before setting up Hub Bridge, check if your client supports Remote URL connections instead:

Client Compatibility Guide

See which clients support Remote URL vs Hub Bridge - Remote URL is simpler if your client supports it

Use Hub Bridge for: Cursor, VS Code, JetBrains IDEs, Windsurf, Claude Code, and other clients that only support local/stdio MCP servers.

Setup: Edit Your Client's Configuration​

Most clients that require Hub Bridge use a JSON configuration file. Here's how to set it up:

Prerequisites​

warning

Make sure you have these before starting:

  • Node.js 18 or higher - Check with node --version
  • Terminal access - macOS/Linux Terminal, Windows PowerShell, or Command Prompt
  • Internet connection - For initial download and authentication
  • Default browser - Bridge opens browser for one-time authentication

Install Node.js (if needed)​

# Using Homebrew (recommended)
brew install node

# Or download from nodejs.org

Configuration by Client​

Each client has its own configuration format and file location. Choose your client below:

File Location: .cursor/mcp.json in your project root

Configuration:

{
  "mcpServers": {
    "civic": {
      "command": "npx",
      "args": ["-y", "@civic/hub-bridge@latest"]
    }
  }
}

Alternative: Use Cursor Settings → Features → MCP → Add New MCP Server

note

All these configurations use the Hub Bridge - your client runs npx -y @civic/hub-bridge locally, and the bridge handles connecting to Civic servers.

Step 2: First Run Authentication​

When you first use an MCP command, the bridge will automatically:

  1. 1
    Create Account & Select Servers
    1. Create your Civic account (Google, GitHub, etc.)
    2. During account creation, select which MCP servers you want to connect (GitHub, Slack, etc.)
  2. 2
    Download & Install

    Bridge downloads itself (happens once, ~30 seconds)

  3. 3
    Open Browser

    Your default browser opens to app.civic.com for authentication

  4. 4
    Ready for Use

    Bridge is now configured and your client can access your selected tools

  5. 5
    App Authorization (As Needed)

    When you first use each specific tool, you'll authorize access to that app (e.g., GitHub OAuth, Slack workspace permission)

Managing Your Server Selection​

You can modify which servers you have access to in two ways:

Option 1: In Chat

"Connect me to GitHub"
"Add Slack to my available tools"  
"Show me what tools are available to connect"
"Remove Dropbox from my tools"

Option 2: On app.civic.com
Visit the website to add or remove servers from your account selection.

Step 3: Test Connection​

Try these commands in your AI client:

"What MCP servers are available?"
"List my GitHub repositories"  
"Show me recent Slack messages"

Troubleshooting​

Common Issues​

Bridge command not found

Problem: npx: command not found or 'npx' is not recognized

Solution:

  • Install Node.js 18+ from nodejs.org
  • Restart your terminal/IDE after installation
  • Verify with node --version and npm --version
Browser doesn't open for auth

Problem: Authentication browser window doesn't appear

Solution:

  • Corporate firewall may be blocking - try from personal network
  • Manually visit the auth URL shown in terminal output
  • Check if default browser is set correctly
  • Try running from regular terminal instead of IDE terminal
Client shows no tools/servers

Problem: Bridge connects but client doesn't see any MCP tools

Solution:

  • Restart your client completely after bridge setup
  • Check that you selected servers during authentication
  • Try using the bridge again to see if it works
  • Some clients need manual restart of MCP features
Authentication keeps failing

Problem: Repeated auth prompts or 401 errors

Solution:

  • Try reinstalling: remove the MCP server from your client and add it back
  • Check system time is accurate (OAuth is time-sensitive)
  • Disable VPN temporarily during initial setup
  • Join our developer community if issue persists
Slow or timing out

Problem: Bridge responses are slow or timeout

Solution:

  • Check internet connection stability
  • Corporate proxy may be interfering - try personal network
  • Some MCP operations are inherently slower (large file operations)
  • Bridge caches auth tokens to minimize delays

Corporate Network Considerations​

If you're on a corporate network:

  • Proxy servers may interfere with authentication - whitelist app.civic.com and *.civic.com
  • Firewall rules might block npm/npx - work with IT to allow Node.js tools
  • Certificate issues - corporate TLS inspection can cause SSL errors
  • Alternative: Try initial setup from personal network, then bridge should work on corporate network

Getting More Help​

  1. 1
    Check Error Messages

    Note any error messages you see when trying to use MCP commands

  2. 2
    Gather Info

    Note your OS, Node version (node --version), and client type

  3. 3
    Contact Support

    Include the above info when contacting support for faster resolution

Still Need Help?

Contact our support team with your specific setup details

How Hub Bridge Works​

The Hub Bridge follows a modular architecture with clear separation of concerns:

Core Components​

  • Bridge Core: Connects stdio and HTTP/SSE transports, forwards messages between client and server
  • Auth Provider: Handles OAuth client interface for Civic authentication with PKCE flow
  • Callback Server: Creates local HTTP server for OAuth redirects with dynamic port selection
  • Token Store: Manages secure storage of authentication tokens with file system persistence
  • OIDC Configuration: Fetches OpenID Connect configuration from discovery endpoints

Authentication Flow​

  1. Civic Authentication: Automatically initiated when bridge starts using PKCE for security
  2. Service-Specific Authentication: Intercepts auth URL errors, opens browser for user authorization
  3. Token Management: Stores tokens locally for subsequent uses, handles refresh automatically

Environment Variables​

The Hub Bridge may support environment variables for configuration, but refer to the official package documentation for the most current and accurate list of supported options.