> ## Documentation Index
> Fetch the complete documentation index at: https://docs.civic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection Methods

> Remote URL vs Hub Bridge - understanding how your AI connects to Civic

## 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:

<div style={{display:'flex',alignItems:'center',justifyContent:'center',gap:'8px',padding:'20px 24px',background:'rgba(124,59,237,0.04)',borderRadius:'8px',border:'1px solid rgba(124,59,237,0.15)',margin:'16px 0',flexWrap:'wrap'}}>
  <span style={{padding:'8px 16px',borderRadius:'6px',background:'rgba(124,59,237,0.10)',fontSize:'13px',fontWeight:'600'}}>Your AI Client</span>
  <span style={{color:'#7C3BED',fontSize:'16px'}}>↔</span>
  <span style={{padding:'8px 16px',borderRadius:'6px',background:'rgba(124,59,237,0.10)',fontSize:'13px',fontWeight:'600'}}>Internet</span>
  <span style={{color:'#7C3BED',fontSize:'16px'}}>↔</span>
  <span style={{padding:'8px 16px',borderRadius:'6px',background:'rgba(124,59,237,0.25)',fontSize:'13px',fontWeight:'700',color:'#7C3BED'}}>Civic Servers</span>
  <span style={{color:'#7C3BED',fontSize:'16px'}}>↔</span>
  <span style={{padding:'8px 16px',borderRadius:'6px',background:'rgba(124,59,237,0.10)',fontSize:'13px',fontWeight:'600'}}>Your Tools</span>
</div>

## 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:

<div style={{display:'flex',alignItems:'center',justifyContent:'center',gap:'8px',padding:'20px 24px',background:'rgba(124,59,237,0.04)',borderRadius:'8px',border:'1px solid rgba(124,59,237,0.15)',margin:'16px 0',flexWrap:'wrap'}}>
  <span style={{padding:'8px 16px',borderRadius:'6px',background:'rgba(124,59,237,0.10)',fontSize:'13px',fontWeight:'600'}}>Your AI Client</span>
  <span style={{color:'#7C3BED',fontSize:'16px'}}>↔</span>
  <span style={{padding:'8px 16px',borderRadius:'6px',background:'rgba(124,59,237,0.25)',fontSize:'13px',fontWeight:'700',color:'#7C3BED'}}>Hub Bridge (local)</span>
  <span style={{color:'#7C3BED',fontSize:'16px'}}>↔</span>
  <span style={{padding:'8px 16px',borderRadius:'6px',background:'rgba(124,59,237,0.10)',fontSize:'13px',fontWeight:'600'}}>Internet</span>
  <span style={{color:'#7C3BED',fontSize:'16px'}}>↔</span>
  <span style={{padding:'8px 16px',borderRadius:'6px',background:'rgba(124,59,237,0.25)',fontSize:'13px',fontWeight:'700',color:'#7C3BED'}}>Civic Servers</span>
  <span style={{color:'#7C3BED',fontSize:'16px'}}>↔</span>
  <span style={{padding:'8px 16px',borderRadius:'6px',background:'rgba(124,59,237,0.10)',fontSize:'13px',fontWeight:'600'}}>Your Tools</span>
</div>

## 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.

<Card title="Learn About Civic Tokens" icon="key" href="/civic/concepts/tokens">
  **Complete guide** to generating and using Civic tokens for automation platforms, agent builders, and custom integrations
</Card>

**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](/civic/concepts/tokens)

## 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!