Skip to main content

Connection Methods

Two Ways to Connect​

There are two ways your AI client can connect to Civic servers. The method depends on what your AI client supports:

Remote URL Method​

Simple copy/paste connection for clients that support remote MCP servers.

How it works:​

  1. Visit app.civic.com and select your tools
  2. Copy the MCP URL: https://app.civic.com/hub/mcp
  3. Paste into your AI client's MCP settings
  4. Your client connects directly to Civic servers

Supported clients:​

  • Claude Desktop
  • Claude.ai (Web)
  • Goose
  • Any client with "remote MCP URL" or "HTTP connector" options

Advantages:​

  • ✅ Simplest setup - just copy and paste
  • ✅ No local software needed
  • ✅ Automatic updates - always uses latest version
  • ✅ Works across devices - same URL everywhere

Connection flow:​

Your AI Client↔Internet↔Civic Servers↔Your Tools

Hub Bridge Method​

Local proxy connection for clients that only support local MCP servers.

How it works:​

  1. Configure your client to run npx -y @civic/hub-bridge as a local MCP server
  2. Your client thinks it's connecting to a local server
  3. The bridge forwards requests to Civic servers
  4. Bridge handles all authentication and token management

Supported clients:​

  • Cursor (one-click install)
  • VS Code (one-click install)
  • JetBrains IDEs (manual setup)
  • Windsurf (manual setup)
  • Claude Code (auto-install: npx @civic/hub-bridge install claude-code)
  • Any client with only "local MCP" or "stdio" options

Advantages:​

  • ✅ Universal compatibility - works with any MCP client
  • ✅ Local control - bridge runs on your machine
  • ✅ Transparent authentication - handles OAuth flows automatically
  • ✅ Offline capability - cached tokens work briefly offline

Connection flow:​

Your AI Client↔Hub Bridge (local)↔Internet↔Civic Servers↔Your Tools

How to Tell Which Method You Need​

Check your AI client's settings:​

Use Remote URL if you see:

  • "Remote MCP server"
  • "HTTP MCP URL"
  • "MCP connector URL"
  • "External MCP server"

Use Hub Bridge if you see:

  • "Local MCP server"
  • "Command/stdio"
  • "MCP executable"
  • "Local process"

Quick test:​

If your client asks for a command and arguments (like npx and [@civic/hub-bridge]), you need Hub Bridge. If it asks for a URL, you can use Remote URL.

Why Two Methods?​

MCP Client Limitations​

Not all AI clients support all MCP features:

Remote URL requirements:

  • HTTP/HTTPS network requests
  • OAuth authentication handling
  • Token refresh management
  • Remote server connections

Hub Bridge compatibility:

  • Only needs local process spawning
  • Bridge handles all network complexity
  • Works with any stdio-based MCP client

Technical Differences​

Remote URL clients:

  • Native MCP HTTP protocol support
  • Built-in OAuth handling
  • Direct network connectivity
  • Usually newer or more advanced clients

Hub Bridge clients:

  • stdio/process-based MCP only
  • No built-in authentication
  • Local-only MCP support
  • Often development tools or older clients

Authentication Methods​

Civic supports two authentication approaches depending on how you're connecting:

Browser Authentication​

For: Claude Desktop, Cursor, VS Code, and other MCP-compatible agents

When connecting through Remote URL or Hub Bridge, Civic uses browser-based OAuth authentication:

  • You authenticate through your browser when connecting
  • Works with all MCP-compatible AI assistants
  • Secure OAuth flow with automatic token refresh
  • No manual token management required

Token-Based Authentication​

For: Services that require an access token upfront

Some services and platforms cannot use browser-based OAuth flows and need a token provided upfront, such as OpenAI Agent Builder, n8n, and custom applications.

Learn About Civic Tokens

Complete guide to generating and using Civic tokens for automation platforms, agent builders, and custom integrations

Quick overview:

  • Generate time-limited tokens (1-30 days) from your Civic dashboard
  • Use tokens for server-side integrations that can't use browser OAuth
  • Tokens are profile-scoped and revocable at any time

Authentication Differences by Method​

Remote URL Authentication:

  • Your client handles OAuth directly
  • You authorize in your client's interface
  • Client manages token storage and refresh

Hub Bridge Authentication:

  • Bridge handles all OAuth flows
  • You authorize in your browser (opened by bridge)
  • Bridge manages tokens locally and refreshes automatically

Token-Based Authentication:

  • You generate a token in Civic dashboard
  • Provide the token to your service/platform
  • Token valid until expiration (configurable up to 30 days)
  • Manually refresh or regenerate as needed
  • Complete token documentation

When to Use Each Method​

Choose Remote URL when:​

  • Your client supports it (check settings for "remote MCP URL")
  • You want the simplest setup
  • You use multiple devices
  • You prefer cloud-based management

Choose Hub Bridge when:​

  • Your client only supports local/stdio MCP
  • You're using development tools (IDEs, CLIs)
  • You want local control over connections
  • Your client doesn't support OAuth

Troubleshooting Connection Issues​

Remote URL problems:​

  • Client doesn't connect: Check if client supports remote MCP URLs
  • Authentication fails: Verify client has OAuth capabilities
  • URL not accepted: Try Hub Bridge method instead

Hub Bridge problems:​

  • Command not found: Install Node.js 18+
  • Bridge won't start: Check terminal permissions and network access
  • Authentication hangs: Ensure browser can open and corporate firewalls aren't blocking

Both Methods Work the Same​

Once connected, your AI experience is identical regardless of connection method:

  • Same tools and capabilities
  • Same authentication to individual services
  • Same performance and reliability
  • Same security and privacy protections

The connection method is just plumbing - what matters is that your AI can access your tools!