Get Your Credentials
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://app.civic.com/hub/mcp
Locking to a Toolkit
For production agents, append a profile parameter to lock the connection to a specific toolkit:
https://app.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
| Parameter | Type | Description |
|---|---|---|
profile | string | Toolkit alias (e.g. support, production-agent) |
lock | "true" | "false" | Default true when profile is set. Set to false to allow toolkit switching. |
skills | string | Comma-separated skill aliases to pre-load (e.g. escalation,triage) |
accountId | string | For multi-account or organization users |
Example URLs:
# Lock to the "sales-agent" toolkit (recommended for production)
https://app.civic.com/hub/mcp?profile=sales-agent
# Load a toolkit and pre-load skills
https://app.civic.com/hub/mcp?profile=support&skills=escalation,triage
# Organization account with a specific toolkit
https://app.civic.com/hub/mcp?profile=ops&accountId=org_abc123
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 Type | Recommended 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 platforms | Civic 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:
- Your client opens a browser window to app.civic.com
- You sign in with your Civic account
- The client receives a session token automatically
- 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
- Log in to app.civic.com
- Complete the onboarding flow — on the Install step, you will see your MCP URL
- Below the URL, select Generate a Civic token — described as "Best for automation platforms and scheduled tasks"
- 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://app.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.
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.
Exchange existing auth tokens for Civic Hub access
Quick Reference
| Scenario | Method | Where to Configure |
|---|---|---|
| Claude Desktop, Claude.ai, Cursor, VS Code | OAuth | Client settings — paste MCP URL |
| LangChain, Vercel AI SDK, custom agents | Civic Token | Environment variables: CIVIC_URL, CIVIC_TOKEN |
| OpenAI Agent Builder | Civic Token | Agent configuration settings |
| n8n, Make, Zapier | Civic Token | HTTP header configuration |
| Interactive testing in Civic Chat | Built-in | No configuration needed |