SendGrid MCP Server

Instructions

Implementation Reference

• src/tools/mail.ts:28-39 (handler)

  The handler function that implements the send_mail tool. It checks if read-only mode is active and, if not, sends the email data as JSON via POST to SendGrid's /v3/mail/send endpoint using makeRequest.

  handler: async (mailData: any): Promise<ToolResult> => {
    const readOnlyCheck = checkReadOnlyMode();
    if (readOnlyCheck.blocked) {
      return { content: [{ type: "text", text: readOnlyCheck.message! }] };
    }
    
    const result = await makeRequest("https://api.sendgrid.com/v3/mail/send", {
      method: "POST",
      body: JSON.stringify(mailData),
    });
    return { content: [{ type: "text", text: `Email sent successfully. Response: ${JSON.stringify(result, null, 2)}` }] };
  },

• src/tools/mail.ts:8-27 (schema)

  The tool configuration object defining the title, description, and inputSchema using Zod for validating parameters such as personalizations, from email, content, and reply_to.

  config: {
    title: "Send Mail",
    description: "Send an email using SendGrid Mail Send API",
    inputSchema: {
      personalizations: z.array(z.object({
        to: z.array(EmailAddressSchema),
        cc: z.array(EmailAddressSchema).optional(),
        bcc: z.array(EmailAddressSchema).optional(),
        subject: z.string().optional(),
        substitutions: z.record(z.any()).optional(),
      })).describe("Personalization settings for recipients"),
      from: EmailAddressSchema,
      subject: z.string().optional().describe("Default subject if not set in personalizations"),
      content: z.array(z.object({
        type: z.string().describe("Content type (text/plain, text/html)"),
        value: z.string().describe("Content body"),
      })).describe("Email content"),
      reply_to: EmailAddressSchema.optional(),
    },
  },

• src/tools/mail.ts:6-41 (registration)

  The mailTools export that defines and registers the send_mail tool object with its config and handler, which is later included in allTools.

  export const mailTools = {
    send_mail: {
      config: {
        title: "Send Mail",
        description: "Send an email using SendGrid Mail Send API",
        inputSchema: {
          personalizations: z.array(z.object({
            to: z.array(EmailAddressSchema),
            cc: z.array(EmailAddressSchema).optional(),
            bcc: z.array(EmailAddressSchema).optional(),
            subject: z.string().optional(),
            substitutions: z.record(z.any()).optional(),
          })).describe("Personalization settings for recipients"),
          from: EmailAddressSchema,
          subject: z.string().optional().describe("Default subject if not set in personalizations"),
          content: z.array(z.object({
            type: z.string().describe("Content type (text/plain, text/html)"),
            value: z.string().describe("Content body"),
          })).describe("Email content"),
          reply_to: EmailAddressSchema.optional(),
        },
      },
      handler: async (mailData: any): Promise<ToolResult> => {
        const readOnlyCheck = checkReadOnlyMode();
        if (readOnlyCheck.blocked) {
          return { content: [{ type: "text", text: readOnlyCheck.message! }] };
        }
        
        const result = await makeRequest("https://api.sendgrid.com/v3/mail/send", {
          method: "POST",
          body: JSON.stringify(mailData),
        });
        return { content: [{ type: "text", text: `Email sent successfully. Response: ${JSON.stringify(result, null, 2)}` }] };
      },
    },
  };

• src/index.ts:21-23 (registration)

  The loop that registers all tools from allTools (including send_mail) with the MCP server by calling server.registerTool for each.

  for (const [name, tool] of Object.entries(allTools)) {
    server.registerTool(name, tool.config as any, tool.handler as any);
  }

• src/tools/index.ts:13-13 (registration)

  Spreads the mailTools (containing send_mail) into the allTools export used for global registration.

  ...mailTools,