Keila MCP Server

This repository contains a Model Context Protocol (MCP) server that acts as a secure, multi-tenant proxy between an AI Assistant and the Keila backend API. It exposes 34 MCP tools covering 6 resource domains with full CRUD, transactional messaging, and system operations.

✨ Features

• 🔑 Identity Passthrough — Extracts the Authorization: Bearer <token> header from incoming HTTP requests and forwards it to the Keila API without server-side authentication.
• 👥 Multi-Tenancy — Uses Python contextvars to maintain thread-safe user identity isolation, ensuring all AI-driven actions are scoped to the authenticated user's permissions.
• 📊 Full Keila Coverage — 34 tools mapped to Keila REST API endpoints across 6 resource domains.
• ⚡ TOON Optimization — Bulk list responses are automatically compressed using TOON (Token-Optimized Object Notation) to reduce token consumption and maximize context window efficiency.
• 🚀 Efficient Gets — GET responses return only commonly used fields by default. Full objects are available via an include_all_fields flag.
• 🧪 Comprehensive Testing — 75 automated tests covering all tool domains, run via the test runner pipeline.

🔧 Environment Variables

Variable	Required	Description
KEILA_BASE_URL	Yes	Docker-internal URL of the Keila API (e.g. http://keila-app:4000).
MCP_SERVER_PORT	Yes	Port number the MCP server listens on
ALLOW_ALL_AGGREGATE	No	When true, aggregate listing tools honor the include_all_fields parameter. When false (default), the parameter is silently forced to False for aggregate list operations.
IS_STATEFUL	No	When true, uses stateful Streamable HTTP with session tracking. When false (default), uses stateless mode.

📦 Installation & Local Development

1. Ensure you have Python 3.12+ installed.
2. Install dependencies:

   pip install fastmcp httpx pydantic uvicorn toon-mcp-server
   

3. Run the server:

   export KEILA_BASE_URL=http://keila-app:4000
   export MCP_SERVER_PORT=80
   python -m src.main
   

🐳 Docker Deployment

Build and run the server using Docker:

docker build -t keila-mcp:latest .
docker run -d --name keila-mcp \
    -e KEILA_BASE_URL="http://keila-app:4000" \
    -e MCP_SERVER_PORT=80 \
    -e ALLOW_ALL_AGGREGATE=false \
    keila-mcp:latest

The MCP server serves at http://keila-mcp:80/mcp (Streamable HTTP).

⚠️ Important Notes

• 📋 include_all_fields — The include_all_fields parameter (available on all get_* and list_* tools) controls whether all available fields are included in responses. Defaults to False for performance; set to True only when additional fields are needed.
• 🔒 ALLOW_ALL_AGGREGATE — Controls whether aggregate listing tools respect the include_all_fields parameter. When set to false (default), all aggregate list operations silently return only default fields regardless of the caller's request.
• ⚡ TOON Compression — All bulk list responses are automatically compressed using TOON to reduce token consumption by 30–60%.
• 📝 Required Fields & Defaults — Each create_* tool requires specific key fields. All other fields default to empty strings or reasonable values.

🛠️ API Tool Mapping

The server implements 34 MCP tools organized into the following categories:

📧 Campaigns (7 tools)

• list_all_campaigns — List all campaign records
• get_campaign_by_id — Get a single campaign by ID
• create_campaign — Create a new campaign
• update_campaign — Update an existing campaign
• delete_campaign_by_id — Delete a campaign by ID
• send_campaign — Queue a campaign for immediate delivery
• schedule_campaign — Schedule a campaign for future delivery

🎯 Segments (5 tools)

• list_all_segments — List all segment records
• get_segment_by_id — Get a single segment by ID
• create_segment — Create a new segment
• update_segment — Update an existing segment
• delete_segment_by_id — Delete a segment by ID

👥 Contacts (7 tools)

• list_all_contacts — List all contact records
• get_contact_by_id — Get a single contact by ID, email, or external ID
• create_contact — Create a new contact
• update_contact — Update an existing contact
• delete_contact_by_id — Delete a contact by ID, email, or external ID
• update_contact_data — Shallow-merge custom data fields on a contact
• replace_contact_data — Replace all custom data fields on a contact

📝 Forms (6 tools)

• list_all_forms — List all form records
• get_form_by_id — Get a single form by ID
• create_form — Create a new form
• update_form — Update an existing form
• delete_form_by_id — Delete a form by ID
• submit_form — Submit a form to create or update a contact

📄 Templates (5 tools)

• list_all_templates — List all template records
• get_template_by_id — Get a single template by ID
• create_template — Create a new template
• update_template — Update an existing template
• delete_template_by_id — Delete a template by ID

🛠️ Senders, Transactional Messages & System Tools (4 tools)

• list_all_senders — List all sender records
• send_transactional_message — Send a transactional message
• render_transactional_message — Render a transactional message without sending it
• check_server_status — Check connectivity to the Keila backend