# Client Setup Reference

Exact setup commands for connecting AI clients to Civic via MCP.

**Base MCP URL:** `https://app.civic.com/hub/mcp`

**With a toolkit:** `https://app.civic.com/hub/mcp?profile=<toolkit-name>`

**Production (locked):** `https://app.civic.com/hub/mcp?profile=<toolkit-name>&lock=true`

**Query params:**
- `profile` — toolkit alias (e.g., `support`, `marketing`)
- `lock` — `"true"` or `"false"` (default: `true` when profile is set)
- `skills` — comma-separated skill aliases to pre-load
- `accountId` — org ID for multi-account users

**Raw API test:**
```bash
curl -X POST https://app.civic.com/hub/mcp \
  -H "Authorization: Bearer $CIVIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'
```

---

## Interactive Clients (OAuth / browser auth)

### Claude Code

Docs: https://docs.civic.com/civic/quickstart/clients/claude-code

**HTTP transport (recommended):**
```bash
claude mcp add --transport http civic https://app.civic.com/hub/mcp
```

**Hub Bridge (alternative):**
```bash
claude mcp add civic "npx @civic/hub-bridge"
```

Then:
1. Launch `claude`
2. Run `/mcp`
3. Select `civic`
4. Authorize in the browser when prompted

Debug: `claude --debug`
Remove: `claude mcp remove civic`

Prerequisites: Anthropic Claude CLI installed, Node.js 18+ (for Hub Bridge only).

### Codex

Docs: https://docs.civic.com/civic/quickstart/clients/codex

**HTTP transport (recommended):**
```bash
codex mcp add civic --transport http https://app.civic.com/hub/mcp
```

**Hub Bridge (alternative):**
```bash
codex mcp add civic -- npx -y @civic/hub-bridge
```

Then: launch `codex`, run `/mcp`, select the server, authorize in browser.

**Desktop App:** Settings > MCP Servers > Add Server > Streamable HTTP > URL: `https://app.civic.com/hub/mcp`

Debug: `codex --debug`
Remove: `codex mcp remove civic`

### Claude Desktop

Docs: https://docs.civic.com/civic/quickstart/clients/claude-desktop

**Pro/Team (MCP Connector):**
Settings > Connectors > Add Custom Connector > Name "Civic" > URL `https://app.civic.com/hub/mcp` > Connect > complete OAuth.

**Free plan (Hub Bridge via config file):**
Edit `claude_desktop_config.json` in Developer settings:
```json
{
  "mcpServers": {
    "civic": {
      "command": "npx",
      "args": ["-y", "@civic/hub-bridge@latest"]
    }
  }
}
```

Requires Node.js 18+.

### Claude.ai (Web)

Docs: https://docs.civic.com/civic/quickstart/clients/claude-web

Add as Remote URL: `https://app.civic.com/hub/mcp`

### Cursor

Docs: https://docs.civic.com/civic/quickstart/clients/cursor

**Config file (`.cursor/mcp.json`):**
```json
{
  "mcpServers": {
    "civic": {
      "command": "npx",
      "args": ["-y", "@civic/hub-bridge"]
    }
  }
}
```

**Manual:** Settings > MCP Servers > Add > stdio > Nickname "Civic" > Command `npx -y @civic/hub-bridge`

Requires Node.js 18+.

### VS Code

Docs: https://docs.civic.com/civic/quickstart/clients/vscode

**Method 1 — `.mcp.json` in project root:**
```json
{
  "servers": {
    "civic": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@civic/hub-bridge"]
    }
  }
}
```

**Method 2 — VS Code Settings > Remote HTTP:**
Name: Civic, Type: http, URL: `https://app.civic.com/hub/mcp`

**Method 3 — VS Code Settings > Local Bridge:**
Name: Civic, Type: stdio, Command: `npx -y @civic/hub-bridge`

Requires VS Code 1.99+, Node.js 18+ (for Hub Bridge).

### Windsurf

Docs: https://docs.civic.com/civic/quickstart/clients/windsurf

Config at `~/.codeium/windsurf/mcp_config.json`:
```json
{
  "mcpServers": {
    "civic": {
      "serverUrl": "https://app.civic.com/hub/mcp"
    }
  }
}
```

**Important:** Uses `serverUrl` (not `url`). Restart Windsurf after changes.

### JetBrains AI

Docs: https://docs.civic.com/civic/quickstart/clients/jetbrains

**UI:** Settings > Tools > AI Assistant > MCP > Name "Civic" > Command `npx` > Arguments `-y mcp-remote https://app.civic.com/hub/mcp`

**Config file (`.jb-mcp.json` in project root or global):**
```json
{
  "servers": [
    {
      "name": "Civic",
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://app.civic.com/hub/mcp"]
    }
  ]
}
```

Requires JetBrains IDE 2025.2+, Node.js 20+.

### Gemini CLI

Docs: https://docs.civic.com/civic/quickstart/clients/gemini

Config at `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
```json
{
  "mcpServers": {
    "civic": {
      "httpUrl": "https://app.civic.com/hub/mcp"
    }
  }
}
```

**Important:** Uses `httpUrl` (not `url` or `serverUrl`). Project config takes precedence over global.

Clear auth cache: `rm -rf ~/.gemini/auth_cache`

### Goose

Docs: https://docs.civic.com/civic/quickstart/clients/goose

Config at `~/.config/goose/config.yaml` (global) or `.goose/config.yaml` (project):

**Remote HTTP:**
```yaml
mcp:
  servers:
    civic:
      type: http
      url: https://app.civic.com/hub/mcp
      name: "Civic"
```

**Hub Bridge alternative:**
```yaml
mcp:
  servers:
    civic:
      type: stdio
      command: npx
      args: ["-y", "@civic/hub-bridge"]
```

Restart: `goose restart` or `goose stop && goose start`

### ChatGPT

Docs: https://docs.civic.com/civic/quickstart/clients/chatgpt

Add as Remote URL: `https://app.civic.com/hub/mcp`

Requires Plus or Enterprise plan.

### Mistral Le Chat

Docs: https://docs.civic.com/civic/quickstart/clients/mistral-lechat

Add as Remote URL: `https://app.civic.com/hub/mcp`

### OpenClaw

Docs: https://docs.civic.com/civic/quickstart/clients/openclaw

**Critical:** Never log into Civic on the same machine where OpenClaw runs. Use a private access token.

**Install skill:**
```bash
clawhub install civictechuser/openclaw-civic-skill
```

**Environment (`~/.openclaw/workspace/.env`):**
```bash
CIVIC_URL="https://app.civic.com/hub/mcp?accountId=YOUR_ACCOUNT_ID&profile=openclaw"
CIVIC_TOKEN="your-access-token"
```

**JSON config (`~/.openclaw/openclaw.json`):**
```json
{
  "skills": {
    "entries": {
      "civic-mcp-bridge": {
        "enabled": true,
        "env": {
          "CIVIC_URL": "your-mcp-url",
          "CIVIC_TOKEN": "your-access-token"
        }
      }
    }
  }
}
```

### Manus

Docs: https://docs.civic.com/civic/quickstart/clients/manus

Connection: Custom Header with Bearer token. Set `Authorization: Bearer <your-civic-token>` in MCP server configuration.

---

## Headless Agents and SDKs (private access token)

All SDK integrations use the same base pattern:
- **URL:** `https://app.civic.com/hub/mcp?profile=<toolkit>&lock=true`
- **Auth:** Bearer token header with your private access token
- **Token env var:** `CIVIC_TOKEN`
- **URL env var:** `CIVIC_URL`

### Anthropic SDK (TypeScript)

Docs: https://docs.civic.com/civic/recipes/anthropic

```bash
npm install @anthropic-ai/sdk
```

```bash
ANTHROPIC_API_KEY=your_anthropic_api_key
CIVIC_TOKEN=your-civic-token-here
CIVIC_URL=https://app.civic.com/hub/mcp
```

```typescript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const response = await client.messages.create({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [{ role: 'user', content: userMessage }],
  mcp_servers: [{
    type: 'url',
    url: process.env.CIVIC_URL!,
    name: 'civic',
    authorization_token: process.env.CIVIC_TOKEN!,
  }],
}, {
  headers: { 'anthropic-beta': 'mcp-client-2025-11-20' },
});
```

**Required header:** `anthropic-beta: mcp-client-2025-11-20`

### OpenAI Agents SDK (TypeScript)

Docs: https://docs.civic.com/civic/recipes/openai-agents

```bash
npm install @openai/agents
```

```typescript
import { Agent, hostedMcpTool, run } from '@openai/agents';

const agent = new Agent({
  name: 'Civic Assistant',
  model: 'gpt-4o-mini',
  instructions: 'You are a helpful assistant with access to external tools through Civic.',
  tools: [
    hostedMcpTool({
      serverLabel: 'civic',
      serverUrl: process.env.CIVIC_URL!,
      authorization: process.env.CIVIC_TOKEN!,
    }),
  ],
});

const result = await run(agent, 'List my GitHub repositories');
console.log(result.finalOutput);
```

### OpenAI SDK (Manual Function Calling)

Docs: https://docs.civic.com/civic/recipes/openai-sdk

```bash
npm install openai @modelcontextprotocol/sdk
```

Uses `StreamableHTTPClientTransport` from `@modelcontextprotocol/sdk/client/streamableHttp.js` and `Client` from `@modelcontextprotocol/sdk/client/index.js`. Maps MCP tools to OpenAI function calling format.

### Vercel AI SDK (Next.js)

Docs: https://docs.civic.com/civic/recipes/vercel-ai-sdk

**Starter repo:**
```bash
git clone https://github.com/civicteam/ai-chatbot.git
cd ai-chatbot && pnpm install && cp .env.example .env.local && pnpm dev
```

**Install (v5):**
```bash
pnpm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/react @modelcontextprotocol/sdk @civic/auth
```

**Install (v6+):**
```bash
pnpm install @ai-sdk/mcp
```

```bash
CIVIC_AUTH_CLIENT_ID=your_client_id
OPENAI_API_KEY=your_openai_key
```

See [civic-auth.md](civic-auth.md) for the full Next.js + Civic Auth setup. The Vercel AI SDK uses `getTokens()` to pass a Civic token to the MCP client via `StreamableHTTPClientTransport`.

Note: v5 imports `experimental_createMCPClient` from `ai`; v6+ imports from `@ai-sdk/mcp`.

### LangChain / LangGraph (Python)

Docs: https://docs.civic.com/civic/recipes/langchain

```bash
pip install langgraph langchain-anthropic langchain-mcp-adapters
```

```bash
CIVIC_URL=https://app.civic.com/hub/mcp?profile=your-toolkit
CIVIC_TOKEN=your-civic-token
ANTHROPIC_API_KEY=your-anthropic-key
```

Uses `MultiServerMCPClient` with `"streamable_http"` transport type and Bearer token auth headers.

Reference repo: https://github.com/titus-civic/langchain-nexus-reference-implementation

### Pydantic AI (Python)

Docs: https://docs.civic.com/civic/recipes/pydantic-ai

```bash
pip install pydantic-ai python-dotenv
```

```python
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

server = MCPServerStreamableHTTP(
    os.environ["CIVIC_URL"],
    headers={"Authorization": f"Bearer {os.environ['CIVIC_TOKEN']}"},
)
agent = Agent("anthropic:claude-sonnet-4-6", mcp_servers=[server])

async with agent.run_mcp_servers():
    result = await agent.run("List open PRs in civicteam/ai-chatbot")
```

**Critical:** Use `mcp_servers=[server]` — not `toolsets=[server]`.

### Google ADK (Python)

Docs: https://docs.civic.com/civic/recipes/google-adk

```bash
pip install google-adk litellm python-dotenv
```

Uses `McpToolset` with `StreamableHTTPConnectionParams`. Note: use `LiteLlm` model wrapper to call Claude directly via Anthropic API (Google ADK's built-in Anthropic support requires Vertex AI).

### CrewAI (Python)

Docs: https://docs.civic.com/civic/recipes/crewai

```bash
pip install crewai anthropic python-dotenv
```

Uses `MCPClient` with `HTTPTransport` (`streamable=True`). Note: `MCPServerAdapter` was removed in CrewAI v1.6.1.

### AutoGen (Python)

Docs: https://docs.civic.com/civic/recipes/autogen

```bash
pip install "autogen-agentchat" "autogen-ext[mcp,anthropic]" python-dotenv
```

Uses `StreamableHttpServerParams` > `mcp_server_tools()` > `AssistantAgent`. Note: Use `mcp_server_tools(server_params)` — not `StreamableHttpMcpToolAdapter`.

### Deep Agents (Python)

Docs: https://docs.civic.com/civic/recipes/deepagents

```bash
pip install deepagents langchain-mcp-adapters langchain-anthropic fastapi uvicorn python-dotenv
```

Reference repo: https://github.com/titus-civic/deepagents-reference-implementation-civic

Run: `uv run uvicorn main:app --reload`

### Additional SDKs

These also have dedicated recipe pages at docs.civic.com:

| Framework | Docs |
|---|---|
| LlamaIndex | https://docs.civic.com/civic/recipes/llamaindex |
| Mastra | https://docs.civic.com/civic/recipes/mastra |
| Semantic Kernel | https://docs.civic.com/civic/recipes/semantic-kernel |
| Haystack | https://docs.civic.com/civic/recipes/haystack |
| DSPy | https://docs.civic.com/civic/recipes/dspy |
| Agno | https://docs.civic.com/civic/recipes/agno |
| CAMEL-AI | https://docs.civic.com/civic/recipes/camel-ai |
| SmolagAgents | https://docs.civic.com/civic/recipes/smolagents |
| Flowise | https://docs.civic.com/civic/recipes/flowise |
| Dify | https://docs.civic.com/civic/recipes/dify |

---

## Starter Repos

| Repo | Stack |
|---|---|
| https://github.com/civicteam/ai-chatbot | Vercel AI SDK + Civic Auth + Next.js |
| https://github.com/titus-civic/langchain-nexus-reference-implementation | LangGraph + Civic |
| https://github.com/titus-civic/deepagents-reference-implementation-civic | Deep Agents + Civic |