Skip to main content

Hermes

Connect a Hermes agent to Civic using its native MCP support. Hermes is a Python CLI agent framework that supports multiple LLM providers (including Anthropic, OpenAI, and others) and MCP for external tool access — pair it with Civic's MCP gateway to give your agent secure access to Gmail, Google Calendar, and 80+ other services.

Prerequisites​

Installation​

Install the Hermes agent with MCP support using uv:

uv add hermes-agent[mcp]

Environment Variables​

# Your full Civic toolkit URL — MUST be wrapped in double quotes
# because the URL contains & characters that bash interprets otherwise
CIVIC_URL="https://app.civic.com/hub/mcp?profile=your-toolkit&lock=true"

# Civic token generated from app.civic.com → Install → MCP URL
CIVIC_TOKEN=your-civic-token

# API key for your chosen LLM provider
ANTHROPIC_API_KEY=your-anthropic-key   # or OPENAI_API_KEY, etc.
warning

The CIVIC_URL contains & characters. Always wrap it in double quotes in your .env file — otherwise bash interprets & as a background operator and silently truncates the URL.

Get Your Credentials

How to generate a Civic token and configure toolkit URL parameters

Configuration​

Create a config.yaml that points Hermes at your Civic MCP gateway:

model:
  provider: anthropic          # or openai, etc.
  model_id: claude-sonnet-4-6  # or gpt-4o, etc.

mcp:
  servers:
    civic:
      url: ${CIVIC_URL}
      authorization: Bearer ${CIVIC_TOKEN}
      timeout: 180

Hermes reads this config at startup and connects to Civic as a Streamable HTTP MCP server. The LLM discovers the available tools automatically.

Running the Agent​

uv run hermes

This starts an interactive CLI session. Ask natural language questions and Hermes will route tool calls through Civic:

You: What events do I have this week?
Hermes: Let me check your Google Calendar...

Telegram Bot​

Hermes also supports running as a Telegram bot. Add your bot token to .env:

TELEGRAM_BOT_TOKEN=your-telegram-bot-token

Then run the bot:

uv run python telegram_bot.py

The bot supports per-user conversation history, automatic message chunking for Telegram's 4,096-character limit, and background typing indicators during tool calls.

Production Configuration​

Lock to a Toolkit​

For production agents, always lock to a specific toolkit using the profile URL parameter:

CIVIC_URL="https://app.civic.com/hub/mcp?profile=your-production-toolkit"

When a profile is specified, the session is locked by default — the agent cannot switch toolkits or modify its own guardrails. This prevents prompt injection attacks from escaping the defined tool scope.

Multi-Account Setup​

For organization accounts, include the accountId parameter:

CIVIC_URL="https://app.civic.com/hub/mcp?profile=support&accountId=org_abc123"

Pre-load Skills​

Load specific Skills at session start using the skills parameter:

CIVIC_URL="https://app.civic.com/hub/mcp?profile=support&skills=escalation,canned-responses"

Reference Implementation​

A complete reference implementation including CLI agent and Telegram bot is available at:

github.com/civicteam/hermes-reference-implementation-civic

Next Steps​

Agent Deployment

Production deployment guide: profile locking, URL params, authentication

Guardrails

Constrain what tools your Hermes agent can use

Audit Trail

Query what your agent did via Civic Chat

Get Credentials

Token generation and URL parameter reference