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

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

<Card title="Agent Deployment" icon="robot" href="/civic/quickstart/clients/agents">
  Full guide to profile locking, skills, and production agent configuration
</Card>

***

## 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](https://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:

```python theme={null}
headers = {"Authorization": f"Bearer {your_civic_token}"}
```

For environment variables (recommended):

```bash theme={null}
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.

<Warning>
  Never paste your Civic token into chat or commit it to source control. Store tokens in environment variables or a secrets manager.
</Warning>

***

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

<Card title="Civic Auth" icon="user" href="/auth/index">
  Add user authentication to your app with Civic Auth
</Card>

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

<Card title="Token Exchange" icon="arrows-rotate" href="/overview/token-exchange">
  Exchange existing auth tokens for Civic Hub access
</Card>

***

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