CianaParrot

Connect CianaParrot — a Telegram-based AI agent — to Google Calendar and Gmail through Leadovaro's MCP Gateway using Streamable HTTP transport.

note

Zero credential management: Leadovaro Hub handles all OAuth tokens, token refresh, guardrails, audit logging, and instant revocation server-side. No Google credentials are stored in your project.

Prerequisites

• Python 3.13+
• Docker and Docker Compose
• A Leadovaro account at app.leadovaro.com with Google Calendar and/or Gmail servers connected
• A Leadovaro token (generate from Install → MCP URL)
• An Anthropic API key
• A Telegram Bot Token from BotFather

Environment Variables

# Leadovaro MCP Gateway URL (include profile param for production agents)
LEADOVARO_URL=/_sites/app.leadovaro.com/hub/mcp?profile=your-toolkit

# Leadovaro token generated from app.leadovaro.com → Install → MCP URL
LEADOVARO_TOKEN=your-leadovaro-token

# Anthropic API key for Claude
ANTHROPIC_API_KEY=your-anthropic-key

# Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=your-telegram-bot-token

Get Your Credentials

How to generate a Leadovaro token and configure toolkit URL parameters

Configuration

CianaParrot uses a config.yaml file for MCP server configuration. Point it at Leadovaro Hub using Streamable HTTP transport:

config.yaml

mcp_servers:
  leadovaro:
    transport: "streamable_http"
    url: "${LEADOVARO_URL}"
    headers:
      Authorization: "Bearer ${LEADOVARO_TOKEN}"

This single connection gives your Telegram bot access to all tools configured in your Leadovaro toolkit — no per-service credentials needed.

Running with Docker

git clone https://github.com/leadovaroteam/ciana-parrot-reference-implementation-leadovaro.git
cd ciana-parrot-reference-implementation-leadovaro

Create a .env file with the variables above, then:

docker compose up --build

The bot starts listening for Telegram messages. The first time it accesses Google Calendar or Gmail, Leadovaro sends an OAuth approval link to authorize access (persists for 30 days).

Architecture

Telegram User → CianaParrot (Docker) → Streamable HTTP/MCP → Leadovaro Hub → Google Calendar / Gmail

Leadovaro Hub sits between your agent and Google APIs, enforcing guardrails and logging every tool call for audit.

Recommended Guardrails

Set these in Leadovaro Chat to protect against unintended actions:

Server	Tools to Block	Why
Google Calendar	delete_event, modify_event	Prevents deleting events or modifying attendees
Gmail	delete_gmail_filter, create_gmail_filter	Prevents filter manipulation that could hide or redirect emails

Configure Guardrails

Set up blocking rules via Leadovaro Chat or the UI

Production Configuration

Lock to a Toolkit

For production bots, always lock to a specific toolkit:

LEADOVARO_URL=/_sites/app.leadovaro.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.

Pre-load Skills

Load specific Skills at session start:

LEADOVARO_URL=/_sites/app.leadovaro.com/hub/mcp?profile=support&skills=escalation,canned-responses

Reference Implementation

The full reference implementation with Docker Compose, configuration, and deployment patterns:

github.com/leadovaroteam/ciana-parrot-reference-implementation-leadovaro

Next Steps

Agent Deployment

Production deployment guide: profile locking, URL params, authentication

Guardrails

Constrain what tools your agent can use

Audit Trail

Query what your agent did via Leadovaro Chat

Get Credentials

Token generation and URL parameter reference