SendGrid MCP Server

Instructions

Implementation Reference

• src/tools/contacts.ts:454-460 (handler)

  The handler function implements the core logic for listing contacts. It constructs a paginated API URL for SendGrid's marketing/contacts endpoint and fetches the results using makeRequest, returning formatted JSON.

  handler: async ({ page_size, page_token }: { page_size?: number; page_token?: string }): Promise<ToolResult> => {
    let url = `https://api.sendgrid.com/v3/marketing/contacts?page_size=${page_size || 100}`;
    if (page_token) url += `&page_token=${page_token}`;
    
    const result = await makeRequest(url);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  },

• src/tools/contacts.ts:446-453 (schema)

  Tool configuration including title, description, and Zod-based inputSchema for validating pagination parameters (page_size and page_token).

  config: {
    title: "List All Contacts",
    description: "List all contacts with optional pagination",
    inputSchema: {
      page_size: z.number().optional().default(100).describe("Number of contacts to return (max 1000)"),
      page_token: z.string().optional().describe("Token for pagination"),
    },
  },

• src/tools/contacts.ts:445-461 (registration)

  The list_contacts tool is defined and registered as a property within the exported contactTools object.

  list_contacts: {
    config: {
      title: "List All Contacts",
      description: "List all contacts with optional pagination",
      inputSchema: {
        page_size: z.number().optional().default(100).describe("Number of contacts to return (max 1000)"),
        page_token: z.string().optional().describe("Token for pagination"),
      },
    },
    handler: async ({ page_size, page_token }: { page_size?: number; page_token?: string }): Promise<ToolResult> => {
      let url = `https://api.sendgrid.com/v3/marketing/contacts?page_size=${page_size || 100}`;
      if (page_token) url += `&page_token=${page_token}`;
      
      const result = await makeRequest(url);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    },
  },

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

  Final MCP server registration of all tools, including list_contacts, by iterating over allTools and calling registerTool for each.

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