Skip to main content
Before connecting an agent or client to Civic, you need two things: the MCP URL and (for agents that run unattended) an authentication token. This page covers both.

​
Your MCP URL

All agents and clients connect to the same base URL: 
https://nexus.civic.com/hub/mcp

​
Locking to a Toolkit

For production agents, append a profile parameter to lock the connection to a specific toolkit: 
https://nexus.civic.com/hub/mcp?profile=your-toolkit-alias
When a profile is set, the session is locked by default — the agent cannot switch toolkits or modify its own guardrails. This is the recommended configuration for production deployments.

​
Full URL Parameter Reference

ParameterTypeDescription
profilestringToolkit alias (e.g. support, production-agent)
lock"true" | "false"Default true when profile is set. Set to false to allow toolkit switching.
skillsstringComma-separated skill aliases to pre-load (e.g. escalation,triage)
accountIdstringFor multi-account or organization users
Example URLs: 
# Lock to the "sales-agent" toolkit (recommended for production)
https://nexus.civic.com/hub/mcp?profile=sales-agent

# Load a toolkit and pre-load skills
https://nexus.civic.com/hub/mcp?profile=support&skills=escalation,triage

# Organization account with a specific toolkit
https://nexus.civic.com/hub/mcp?profile=ops&accountId=org_abc123

Agent Deployment

Full guide to profile locking, skills, and production agent configuration

​
Authentication: OAuth vs Token

Civic supports two authentication methods depending on how your agent or client connects.
Client TypeRecommended Method
Interactive clients (Claude Desktop, Cursor, VS Code, etc.)OAuth — browser-based sign-in flow
Automated agents (LangChain, Vercel AI SDK, custom code)Civic Token — bearer token in Authorization header
CLI tools (Goose, Gemini CLI)OAuth — browser sign-in at setup
OpenAI Agent Builder, n8n, automation platformsCivic Token

​
OAuth (Interactive Clients)

For interactive clients, Civic uses the standard MCP authorization flow. When you add the MCP URL to your client and connect:
  1. Your client opens a browser window to nexus.civic.com
  2. You sign in with your Civic account
  3. The client receives a session token automatically
  4. No manual token management required
This is the default for all interactive clients. See individual client setup guides for the exact steps.

​
Civic Tokens (Agents and Automation)

For agents and automated workflows that cannot perform browser-based OAuth, generate a Civic token:

​
Generate a Token

  1. Log in to nexus.civic.com
  2. Complete the onboarding flow — on the Install step, you will see your MCP URL
  3. Below the URL, select Generate a Civic token — described as “Best for automation platforms and scheduled tasks”
  4. Click Generate token and copy it immediately — it will not be shown again

​
Using Your Token

Pass the token as a Bearer token in the Authorization header: 
headers = {"Authorization": f"Bearer {your_civic_token}"}
For environment variables (recommended): 
CIVIC_TOKEN=your-token-here
CIVIC_URL=https://nexus.civic.com/hub/mcp?profile=your-toolkit

​
Token Expiry

Tokens expire after 30 days. Set a calendar reminder to regenerate before expiry. If a token expires, your agent will receive authentication errors until a new token is configured.
Never paste your Civic token into chat or commit it to source control. Store tokens in environment variables or a secrets manager.

​
For App Builders: Identifying Users

If you are building an app where end users should each have their own Civic connection, you have two options: Civic Auth — Use Civic’s user authentication system to identify users. Users log in via Civic Auth, and you can exchange their Civic Auth token for a Civic Hub session. Recommended for new apps.

Civic Auth

Add user authentication to your app with Civic Auth
Existing auth providers — If you already have user authentication (Auth0, Supabase, etc.), use the token exchange flow to link your existing user sessions to Civic.

Token Exchange

Exchange existing auth tokens for Civic Hub access

​
Quick Reference

ScenarioMethodWhere to Configure
Claude Desktop, Claude.ai, Cursor, VS CodeOAuthClient settings — paste MCP URL
LangChain, Vercel AI SDK, custom agentsCivic TokenEnvironment variables: CIVIC_URL, CIVIC_TOKEN
OpenAI Agent BuilderCivic TokenAgent configuration settings
n8n, Make, ZapierCivic TokenHTTP header configuration
Interactive testing in Civic ChatBuilt-inNo configuration needed