acs-email

The ACS Email MCP Server is a .NET 8 MCP implementation designed to run as an Azure Functions custom handler. It leverages Azure Communication Services (ACS) to provide automated email capabilities, including templated emails, attachments, and incident-based notifications. The server exposes MCP tools such as SendEmail, SendSimpleEmail, SendEmailWithMultipleAttachments, SendIncidentEmail, and ListEmailTemplates, enabling you to perform common email workflows directly through MCP payloads. Health and readiness endpoints (/api/healthz and /api/ready) help you monitor the service in production, while infrastructure as code (Bicep templates) simplifies deployment to Azure. Local development and testing are supported via standard .NET tooling and Azure Functions Core Tools.

Prerequisites:

• .NET 8 SDK (https://dotnet.microsoft.com/download/dotnet/8.0)
• Azure Functions Core Tools (https://learn.microsoft.com/azure/azure-functions/functions-run-local)
• Azure Developer CLI (azd) (https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd)
• Visual Studio Code (optional but recommended)
• An Azure subscription with a configured Azure Communication Services Email resource

Installation steps:

1. Clone the repository and navigate into it git clone https://github.com/lukemurraynz/acs-email-mcp.git cd acs-email-mcp

2. Restore and build the project dotnet restore dotnet build

3. Configure local environment

   • Create or update local.settings.json with ACS_ENDPOINT and DEFAULT_SENDER_ADDRESS, or set them in your environment.
   • Example local.settings.json snippet: { "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "UseDevelopmentStorage=true", "ACS_ENDPOINT": "https://<your-acs-resource>.communication.azure.com", "DEFAULT_SENDER_ADDRESS": "donotreply@yourdomain.example" } }

4. Run locally (as an Azure Functions custom handler) func start

5. Run unit/integration tests dotnet test

6. Deploy to Azure azd up

Notes:

• Ensure your sender domain is verified in ACS and that you have proper permissions for sending emails.
• The server is intended to run as an Azure Functions custom handler, so the runtime host should be configured accordingly in production.

Tips and common issues:

• DomainNotLinked and Unauthorized errors typically stem from ACS configuration issues or missing permissions. Verify your ACS domain bindings and managed identities.
• For production deployments, ensure your environment variables (ACS_ENDPOINT, DEFAULT_SENDER_ADDRESS) are securely provided via managed identities or Key Vault references.
• The MCP endpoints exposed by the server include health and readiness checks at /api/healthz and /api/ready. Use these for Kubernetes or orchestrator health checks.
• If you enable attachments or templates, ensure the specified templates exist in your ACS resource and that attachment content types are correctly handled by the server.
• Debug locally with func start and inspect logs for detailed error messages when troubleshooting.