AI Integration Prompt

Copy-paste prompt for AI assistants to connect your agent to Civic — works with Anthropic SDK, OpenAI Agents, LangChain, Pydantic AI, Vercel AI SDK, and more

Use this prompt with your preferred AI assistant (Claude, Cursor, ChatGPT, etc.) to connect your AI agent to Civic. The prompt covers guardrails, audit logging, secret management, and access to 95+ MCP servers.

How to Use

1. Copy the prompt below and paste it into your AI assistant
2. Tell the assistant which agent framework you’re using (Anthropic SDK, LangChain, OpenAI Agents, etc.)
3. The assistant will walk you through setting up your MCP connection with the correct code for your framework
4. Configure security at app.civic.com — guardrails, toolkits, and audit are managed in the platform, not in code

Integration Prompt

# Civic Hub Integration Prompt — Connect Your AI Agent to Civic

## What is Civic Hub?
Civic Hub is a hosted MCP gateway that sits between your AI agent and 85 real-world tool servers (Gmail, Slack, Google Drive, Salesforce, GitHub, databases, and more). It handles security (guardrails), audit logging, secret management, and instant revocation — all server-side. Your code only needs to establish an MCP connection.

## CRITICAL: What NOT To Do
- Do NOT write custom guardrail code, middleware, or interceptors
- Do NOT create audit logging wrappers around tool calls
- Do NOT implement revocation logic in application code
- Do NOT generate mock Civic classes or decorators
Guardrails, audit, and revocation are configured in the Civic platform (app.civic.com), NOT in code.

## Prerequisites
1. Sign up at https://app.civic.com (free trial: 10,000 credits, 14 days)
2. Complete onboarding: select your AI framework and tools
3. On the Install step, generate a Civic token (best for automation)
4. Copy the MCP URL and token

## Environment Variables
Set these in your project:

CIVIC_URL=https://app.civic.com/hub/mcp?profile=your-toolkit CIVIC_TOKEN=your-token-here

## Step 1: Identify Your Framework
Ask the user which agent framework or MCP client they're using, then follow the matching section below.

## Step 2: Connect to Civic Hub

### Anthropic SDK (TypeScript)
```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.messages.create(
  {
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "List my upcoming calendar events" }],
    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" },
  }
);

Note: Use client.messages.create (NOT client.beta.messages). The parameter is mcp_servers (not tools). Field is authorization_token, not { type: 'bearer', token }.

OpenAI Agents SDK (TypeScript)

import { Agent, hostedMcpTool, run } from "@openai/agents";

const agent = new Agent({
  name: "Civic Agent",
  tools: [
    hostedMcpTool({
      serverLabel: "civic",
      serverUrl: process.env.CIVIC_URL,
      authorization: process.env.CIVIC_TOKEN, // plain string, NOT { type: 'bearer', token }
    }),
  ],
});

const result = await run(agent, "List my upcoming calendar events");

Note: openai is bundled as a dependency of @openai/agents — no separate install needed.

LangChain / LangGraph (Python)

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient({
    "civic": {
        "url": os.environ["CIVIC_URL"],
        "transport": "streamable_http",
        "headers": {"Authorization": f"Bearer {os.environ['CIVIC_TOKEN']}"},
    }
})

tools = await client.get_tools()
agent = create_react_agent("claude-sonnet-4-5", tools)
result = await agent.ainvoke({"messages": [{"role": "user", "content": "List my calendar events"}]})

Package: pip install langchain-mcp-adapters langgraph

Pydantic AI (Python)

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

civic_server = MCPServerStreamableHTTP(
    os.environ["CIVIC_URL"],
    headers={"Authorization": f"Bearer {os.environ['CIVIC_TOKEN']}"},
)

agent = Agent("anthropic:claude-sonnet-4-6", mcp_servers=[civic_server])

async with agent.run_mcp_servers():
    result = await agent.run("List my upcoming calendar events")

Package: pip install pydantic-ai

Vercel AI SDK (TypeScript)

import { experimental_createMCPClient as createMCPClient } from "ai"; // use @ai-sdk/mcp for v6+
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { anthropic } from "@ai-sdk/anthropic";
import { streamText } from "ai";

const transport = new StreamableHTTPClientTransport(
  new URL(process.env.CIVIC_URL),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${process.env.CIVIC_TOKEN}` },
    },
  }
);

const mcpClient = await createMCPClient({ transport });
const tools = mcpClient.tools();

const result = streamText({
  model: anthropic("claude-sonnet-4-5"),
  tools,
  prompt: "List my upcoming calendar events",
});

Packages: pnpm install ai @ai-sdk/anthropic @modelcontextprotocol/sdk v6+: import experimental_createMCPClient from "@ai-sdk/mcp" instead of "ai".

Any Other Framework (Generic MCP)

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    url=os.environ["CIVIC_URL"],
    headers={"Authorization": f"Bearer {os.environ['CIVIC_TOKEN']}"}
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        # Use tools with your framework's tool-calling mechanism

Package: pip install mcp

Interactive Clients (Claude Desktop, Cursor, VS Code, etc.)

No code needed. Add this MCP URL in your client’s MCP settings:

https://app.civic.com/hub/mcp

A browser window will open for OAuth sign-in. That’s it.

Step 3: Configure Security (In the Platform, Not Code)

After connecting, the developer configures security at app.civic.com:

• Guardrails: Block PII, credit cards, prompt injection; redact sensitive data from responses
• Toolkits: Group MCP servers into focused profiles (e.g., “support” = Gmail + Slack)
• Audit logs: Query what the agent did via Civic Chat
• Revocation: Instantly block tools, servers, or entire toolkits

None of this requires application code. It’s all managed in the Civic platform.

Error Handling

When integrating Civic, add handling for these failure cases:

Authentication failures — Token expired (30-day expiry) or missing. The MCP client will receive an HTTP 401. Handle by prompting the developer to regenerate the token at app.civic.com.

# Python example
try:
    async with agent.run_mcp_servers():
        result = await agent.run(user_message)
except Exception as e:
    if "401" in str(e) or "Unauthorized" in str(e):
        raise RuntimeError("Civic token expired or invalid. Regenerate at app.civic.com")
    raise

Guardrail blocks — If a guardrail blocks a tool call (e.g., PII detected in the request), the tool call returns an error response — not a crash. The agent will see the error and can inform the user or try a different approach. No special error handling is needed; the agent handles this naturally.

No tools returned — The MCP URL may be missing ?profile=your-toolkit, or the toolkit has no servers configured. Check CIVIC_URL includes the profile parameter.

Transport mismatch — Civic uses Streamable HTTP. If you see connection errors, verify your framework is not trying to connect via stdio or plain SSE.

Common Issues

• Auth errors: Token may be expired (30-day expiry). Regenerate at app.civic.com
• No tools: MCP URL may be missing ?profile=your-toolkit. Check the toolkit name
• Connection errors: Civic uses Streamable HTTP transport, not stdio or plain SSE
• Docs: Full framework guides at https://docs.civic.com/civic/quickstart

All Framework Guides

• Anthropic SDK: https://docs.civic.com/civic/recipes/anthropic
• OpenAI Agents SDK: https://docs.civic.com/civic/recipes/openai-agents
• OpenAI SDK: https://docs.civic.com/civic/recipes/openai-sdk
• LangChain: https://docs.civic.com/civic/recipes/langchain
• Vercel AI SDK: https://docs.civic.com/civic/recipes/vercel-ai-sdk
• Pydantic AI: https://docs.civic.com/civic/recipes/pydantic-ai
• Google ADK: https://docs.civic.com/civic/recipes/google-adk
• CrewAI: https://docs.civic.com/civic/recipes/crewai
• Full list: https://docs.civic.com/civic/quickstart

Correct vs. Incorrect Output

After pasting the prompt, review what your AI assistant generates. Here’s how to tell if it got it right:

Correct

# 5-10 lines: connect to Civic via MCP, pass env vars
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])

The AI generated an MCP connection. Guardrails, audit, and revocation are handled by Civic server-side. No security code needed in your app.

Incorrect — Regenerate

# WRONG: custom guardrail middleware
class CivicGuardrail:
    def __init__(self, rules):
        self.rules = rules
    def validate(self, request):
        for rule in self.rules:
            if rule.matches(request):
                raise BlockedRequestError(...)

# WRONG: custom audit logging
class CivicAuditLogger:
    def log_tool_call(self, tool, params, response):
        self.db.insert({"tool": tool, "params": params, ...})

# WRONG: custom revocation
def revoke_agent_access(agent_id, scope="all"):
    requests.post(f"https://api.civic.com/revoke/{agent_id}", ...)

If the AI generates guardrail classes, audit wrappers, revocation handlers, or any Civic-specific middleware — it hallucinated. None of this exists. Regenerate with the prompt.

Verify Your Integration

After the AI generates code, check these three things before running:

1. Environment variables, not hardcoded tokens

   Confirm CIVIC_URL and CIVIC_TOKEN are read from process.env or os.environ — never hardcoded in source. If the AI put a token string directly in the code, move it to .env.

2. Correct transport type

   Civic uses Streamable HTTP, not stdio or plain SSE. Look for streamable_http, StreamableHTTPClientTransport, or type: "url" in the generated code. If you see type: "stdio" or a subprocess spawn — that’s wrong.

3. No invented APIs

   The generated code should only call your framework’s standard MCP client methods (e.g., messages.create, hostedMcpTool, MCPServerStreamableHTTP). If it imports from civic, @civic/hub, or civic-guardrails — those packages don’t exist.

What the AI Assistant Will Do

When you use this prompt, the AI assistant will:

1. Ask which framework you’re using (Anthropic SDK, OpenAI Agents, LangChain, etc.)
2. Generate the connection code — typically 5-15 lines to connect to Civic via MCP
3. Set up environment variables for your MCP URL and token
4. Point you to app.civic.com for guardrail and toolkit configuration

Supported AI Assistants

This prompt has been tested with:

• Claude (Anthropic)
• Cursor (with Claude)
• ChatGPT (OpenAI)
• GitHub Copilot Chat

Make sure your AI assistant has the ability to run terminal commands and edit files in your project.