DEV Community

TemplateMaster
TemplateMaster

Posted on

Give Your AI Agent the Power to Generate PDFs and Send Emails with an MCP Server

#tutorial #ai #api #mcp

What if your AI assistant could look up an invoice template, fill it with data, generate the PDF and email it to a customer, all from a single prompt?

TemplateMaster exposes a Model Context Protocol (MCP) server. Any MCP-compatible agent (a desktop assistant, an IDE agent, or your own) can search your templates, generate documents and send emails, under the same rules as the REST API: permissions, quotas and strict per-organization data isolation.

In this article we'll connect an agent to it, walk through the permission model, and look at what a typical document-generation run looks like.

📚 Source: official documentation — MCP Server

🔌 Connection details

Server URL https://mcp.templatemaster.fr/mcp
Transport Streamable HTTP
Authentication X-API-KEY: <API_KEY> header

🔑 Header gotcha: send your API key in the X-API-KEY header on every request, exactly like the REST API. Authorization: Bearer is not accepted for API keys; a key sent that way is rejected with a 401.

⚙️ Setup in 5 steps

1. Create an API key

In TemplateMaster, open Settings → API Keys and click Generate New Key. The same key can serve both the REST API and MCP.

2. Enable the key's MCP permissions

On the key's row, click MCP permissions and tick only the capabilities the agent needs. MCP access is disabled by default: a key without any MCP permission is refused by the server.

3. Configure your MCP client

Declare a remote MCP server using the Streamable HTTP transport, the URL above and the X-API-KEY header:

{
  "mcpServers": {
    "templatemaster": {
      "type": "http",
      "url": "https://mcp.templatemaster.fr/mcp",
      "headers": {
        "X-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

The exact config format depends on your MCP client and version, so check its docs for the remote HTTP server syntax. And never commit your API key to a repository.

4. Discover the tools

Once connected, your client lists the available tools. Only the tools allowed by the key's permissions appear.

5. Make a first request

Ask your agent to list your document templates. It calls list_templates and displays the result.

⚠️ Signed requests: if Signed requests required is enabled for your organization (Settings → API Keys), MCP access is refused, because MCP clients can't HMAC-sign every request. Use the standard API Key only mode to use MCP.

🛡️ Permissions: least privilege by design

Each API key has its own MCP permissions. Deletions are never available to agents.

Permission Scope Allows
Read templates mcp.templates.read list_templates, get_template and template resources
Read documents mcp.documents.read get_document, list_documents
Generate documents mcp.documents.generate generate_document (counts toward the monthly document quota)
Read email status mcp.emails.read get_email_status
Send emails (sensitive) mcp.emails.send send_email: real emails to external recipients (counts toward the email quota)

My practical advice: create a dedicated key per agent, and don't grant mcp.emails.send unless that agent truly needs it. An agent that can only read templates and generate PDFs can't email anything to anyone, whatever a prompt tells it.

🧰 The tools

Tools always act on the organization that owns the API key. An agent can never reach another organization's data.

Tool Description
list_templates Search your organization's document and email templates (search, type, pagination)
get_template Template details: type, versions and expected data variables
generate_document Generate a PDF from a document template and JSON data. Asynchronous: returns a documentId
get_document Document status (pending, retrying, generated, failed) and a temporary download link once generated
list_documents List your organization's documents (search, type, period, pagination)
send_email Send an email from an email template (HTML or MJML) to one or more recipients, with optional attachments
get_email_status Processing status of an email (pending, retrying, sent, failed)

The server also exposes read-only resources, templatemaster://templates and templatemaster://templates/CODE, with your template catalog.

🚶 A typical run

To generate a document, an agent chains these tools. You can do the same by hand in an MCP test client:

  1. list_templates: find the template and copy its code.
  2. get_template: read the variables list to build the data object (a dot means nesting: customer.name).
  3. generate_document: send templateCode and data, and keep the returned documentId.
  4. get_document: call it until the status is generated, then open temporaryDownloadUrl.

Here's what the generate_document arguments look like:

{
  "templateCode": "3f2a9c1e-5b7d-4c21-9e0a-7d6b8f1c2a44",
  "data": {
    "invoice_number": "INV-10023",
    "customer": { "name": "John Doe" },
    "items": [
      { "label": "T-shirt", "price": "19.90" }
    ]
  },
  "fileName": "INV-10023.pdf"
}
Enter fullscreen mode Exit fullscreen mode

Two things to remember:

  • ⏱️ Everything is asynchronous. generate_document and send_email answer immediately with an identifier. Poll get_document / get_email_status for the outcome.
  • 🔗 Download links are short-lived (about 60 seconds). Call get_document again to get a fresh one.

💬 What it feels like

Once connected, you can simply say:

"Generate invoice INV-10023 for John Doe, one T-shirt at 19.90, and give me the PDF."

The agent finds the invoice template, reads its variables, builds the JSON above, generates the document, waits for it, and hands you the link. Add the mcp.emails.send permission and "…then email it to john@example.com" works too, which is exactly why that permission is flagged as sensitive.

🧯 Error handling

Tool errors come back as a message starting with a stable code, for example TEMPLATE_NOT_FOUND: .... No internal detail is leaked; unexpected errors include a correlation ID for support.

Code Meaning
UNAUTHORIZED Missing/invalid/inactive key, key without MCP permission, or key not sent in X-API-KEY
FORBIDDEN The key lacks the permission required by this tool
TEMPLATE_NOT_FOUND Unknown, deleted, or belonging to another organization
DOCUMENT_NOT_FOUND Unknown document, or belonging to another organization
INVALID_INPUT Invalid argument (type, format, size, email address…)
QUOTA_EXCEEDED Your plan's monthly limit is reached
GENERATION_FAILED The document couldn't be generated
EMAIL_FAILED The email couldn't be queued
INTERNAL_ERROR Unexpected error: contact support with the correlation ID

Because the codes are stable, an agent (or your own code) can react to them reliably, for instance by telling the user "quota reached" instead of retrying forever.

🔒 Security model

  • The organization comes from the API key only. No tool accepts an organization ID.
  • Another organization's resources are reported exactly like nonexistent ones, so nothing leaks through error messages.
  • Inputs are validated and bounded (data size, number of recipients and attachments, pagination), and requests are rate-limited per key.
  • Every tool call is logged and audited (MCP source), without logging the data you send.
  • Monthly quotas apply exactly as for the REST API.

OAuth 2.1 (optional)

On deployments where it's enabled, the MCP server also accepts OAuth 2.1 access tokens issued by your organization's authorization server, in addition to API keys. Tokens go in Authorization: Bearer; API keys always stay in X-API-KEY. Contact the TemplateMaster team to enable it.

🎯 Wrapping up

The MCP server turns document generation into something an agent can do safely: scoped keys, no delete access, strict isolation, quotas, auditing. Start with a read-only key to let the agent explore your templates, then add generate once you trust the workflow, and keep send for last.

Related docs: API key configuration and the .NET integration if you'd rather call TemplateMaster from C# code.

👉 Full documentation: templatemaster.fr/fr/documentation/mcp-server

Are you already giving agents access to business tools? What guardrails do you put in place? Let me know in the comments! 👇

Top comments (0)