Get Your Credentials

Everything you need before connecting an agent or client to Civic

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

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

1. Your client opens a browser window to app.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 app.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://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.

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

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