Contact Forms and Action Endpoints for AI Agents

For most of the web's history, contact forms existed purely as a human interface. A visitor fills in their name, email, and message, clicks submit, and the data lands in someone's inbox. The form itself was never designed to be understood or operated by anything other than a human with a mouse and keyboard.

That assumption no longer holds. AI agents are increasingly browsing the web on behalf of users, researching products, comparing services, and initiating conversations with businesses. When an AI agent lands on your website and wants to take action, the contact form is the most natural point of interaction. But most forms are invisible to agents. They lack semantic markup, machine-readable descriptions, and programmatic endpoints that would allow an agent to understand what the form does and submit data on the user's behalf.

This guide covers everything you need to build contact forms that work for both humans and AI agents. We cover HTML semantics, the data-mcp-tool attribute system for browser-based agents, JSON API endpoints for server-side agents, honeypot spam protection that does not block legitimate agent traffic, Schema.org ContactPoint structured data, and email notification setup with Resend.

Use the AgentReady scanner to check whether your current contact forms are discoverable by AI agents.

Why contact forms matter for AI agents

AI agents interact with the web in two fundamentally different ways. The first is reading: crawling content, indexing pages, and retrieving information to answer user questions. The second is acting: performing tasks on behalf of users like submitting forms, booking appointments, and requesting quotes.

Most of the AI readiness conversation in 2024-2025 focused on the reading layer: making sure your content is discoverable via llms.txt, robots.txt, and structured data. But the action layer is where the real value lies. When an AI agent can interact with your business programmatically, it opens up entirely new acquisition channels.

The agent interaction model

Consider how an AI agent might interact with your business today:

1. A user asks their AI assistant: "Find me a web development agency that builds AI-powered applications and send them my project brief."
2. The agent searches the web, reads your llms.txt and context.md files, and determines you are a good fit.
3. The agent navigates to your contact page and looks for a way to submit the inquiry.
4. If your form has proper semantic markup and data-mcp-tool attributes, the agent fills in the fields and submits the form.
5. If your site also exposes a JSON API endpoint, a server-side agent can bypass the form entirely and submit structured data directly.

Without proper form structure, step 3 fails. The agent cannot determine what the form does, which fields are required, or how to submit data. Your business never receives the inquiry.

Browser agents versus server-side agents

There are two types of AI agents that interact with forms, and each requires a different approach:

Browser-based agents operate within a web browser context. Chrome 146+ introduced the WebMCP protocol, which allows AI assistants built into the browser to discover and interact with page elements. These agents read HTML attributes like data-mcp-tool and data-mcp-description to understand what interactive elements do. They interact with your form the same way a human would: filling in fields and clicking submit.

Server-side agents operate programmatically without a browser. They make HTTP requests to API endpoints, sending structured JSON data and receiving structured responses. These agents do not see your HTML at all. They rely on API documentation, MCP server manifests, and llms.txt to discover available endpoints. For these agents, you need a JSON API route that accepts form submissions.

The best approach is to support both: a well-structured HTML form with MCP attributes for browser agents, and a JSON API endpoint at the same path for server-side agents.

Building an accessible, well-structured contact form

Before adding any agent-specific attributes, the foundation must be right. A form that is accessible and semantically correct is inherently easier for AI agents to understand.

HTML structure

Every form field should have a proper <label> element associated via the for attribute. This is the single most important thing you can do for both accessibility and agent readability. AI agents use label text to understand what each field expects.

<form
  action="/api/contact"
  method="POST"
  data-mcp-tool="contact_form"
  data-mcp-description="Submit an inquiry to the p0stman team"
>
  <div>
    <label for="name">Full Name</label>
    <input
      type="text"
      id="name"
      name="name"
      required
      autocomplete="name"
      placeholder="Jane Smith"
    />
  </div>

  <div>
    <label for="email">Email Address</label>
    <input
      type="email"
      id="email"
      name="email"
      required
      autocomplete="email"
      placeholder="jane@company.com"
    />
  </div>

  <div>
    <label for="company">Company (optional)</label>
    <input
      type="text"
      id="company"
      name="company"
      autocomplete="organization"
      placeholder="Acme Corp"
    />
  </div>

  <div>
    <label for="message">Message</label>
    <textarea
      id="message"
      name="message"
      required
      rows="5"
      placeholder="Tell us about your project..."
    ></textarea>
  </div>

  <button type="submit">Send Message</button>
</form>

Key HTML principles for agent readability

• Use <label> elements with for attributes. AI agents parse label text to understand field purpose. Never use placeholder text as a substitute for labels.
• Use semantic type attributes. type="email" tells agents the field expects an email address. type="tel" expects a phone number. type="url" expects a URL.
• Use the name attribute consistently. Use clear, descriptive names like name, email, message, company, phone. Avoid obscure names like field_1 or q7.
• Mark required fields with the required attribute. This tells agents which fields must be filled in before submission.
• Use autocomplete attributes. These provide additional semantic hints about what data each field expects.
• Use a <form> element with an action attribute. Even if you handle submission with JavaScript, the action attribute tells agents where to send data.

Styling the form with Tailwind CSS

The form needs to look good for human visitors while maintaining all the semantic structure agents need. Here is a production-ready Tailwind CSS example:

<form
  action="/api/contact"
  method="POST"
  data-mcp-tool="contact_form"
  data-mcp-description="Submit an inquiry to the sales team"
  class="space-y-6 max-w-lg"
>
  <div>
    <label for="name" class="block text-sm font-medium text-gray-700 mb-1">
      Full Name
    </label>
    <input
      type="text"
      id="name"
      name="name"
      required
      autocomplete="name"
      class="w-full px-4 py-3 border border-gray-300 rounded-lg
             focus:ring-2 focus:ring-blue-500 focus:border-transparent
             text-gray-900 placeholder-gray-400"
      placeholder="Jane Smith"
    />
  </div>

  <div>
    <label for="email" class="block text-sm font-medium text-gray-700 mb-1">
      Email Address
    </label>
    <input
      type="email"
      id="email"
      name="email"
      required
      autocomplete="email"
      class="w-full px-4 py-3 border border-gray-300 rounded-lg
             focus:ring-2 focus:ring-blue-500 focus:border-transparent
             text-gray-900 placeholder-gray-400"
      placeholder="jane@company.com"
    />
  </div>

  <div>
    <label for="message" class="block text-sm font-medium text-gray-700 mb-1">
      Message
    </label>
    <textarea
      id="message"
      name="message"
      required
      rows="5"
      class="w-full px-4 py-3 border border-gray-300 rounded-lg
             focus:ring-2 focus:ring-blue-500 focus:border-transparent
             text-gray-900 placeholder-gray-400 resize-y"
      placeholder="Tell us about your project..."
    ></textarea>
  </div>

  <button
    type="submit"
    class="w-full py-3 px-6 bg-blue-600 text-white rounded-lg
           font-medium hover:bg-blue-700 transition-colors"
  >
    Send Message
  </button>
</form>

The data-mcp-tool attribute system

The data-mcp-tool attribute is a convention introduced alongside the WebMCP protocol for browser-based AI agents. It marks HTML elements as interactive tools that agents can discover and use. Think of it as a machine-readable label that tells an AI agent: "This element does something, and here is what."

How data-mcp-tool works

Two attributes work together:

• data-mcp-tool gives the tool a machine-readable name. Use snake_case naming: contact_form, signup_form, book_demo, request_quote.
• data-mcp-description provides a human-readable description of what the tool does. Write this for an AI audience: be specific about the action and outcome.

<!-- Contact form -->
<form
  data-mcp-tool="contact_form"
  data-mcp-description="Submit an inquiry to the sales team. Requires name, email, and message."
>
  ...
</form>

<!-- Newsletter signup -->
<form
  data-mcp-tool="newsletter_signup"
  data-mcp-description="Subscribe to the weekly newsletter. Requires email address only."
>
  ...
</form>

<!-- Book a demo button -->
<a
  href="/book-demo"
  data-mcp-tool="book_demo"
  data-mcp-description="Schedule a 30-minute product demo. Opens a Calendly scheduling page."
>
  Book a Demo
</a>

<!-- Download resource -->
<a
  href="/api/download/whitepaper.pdf"
  data-mcp-tool="download_resource"
  data-mcp-description="Download the AI readiness whitepaper as a PDF. No login required."
>
  Download Whitepaper
</a>

Where to add data-mcp-tool attributes

Add these attributes to any interactive element on your site that represents a meaningful action:

Element	Tool Name	Description
Contact form	contact_form	Submit an inquiry to the team
Signup form	signup	Create a new account
Newsletter form	newsletter_signup	Subscribe to email updates
Demo booking button	book_demo	Schedule a product demonstration
Pricing CTA	view_pricing	View pricing plans and tiers
Search bar	search_content	Search the knowledge base

Writing effective MCP descriptions

The data-mcp-description attribute is what the AI agent reads to decide whether to use the tool. Write it like you are instructing a competent assistant:

• Be specific about the action: "Submit an inquiry to the sales team" not "Contact us"
• State required inputs: "Requires name, email, and message" helps the agent know what to provide
• Describe the outcome: "Response within 24 hours" or "Redirects to a confirmation page"
• Note any constraints: "Business hours only" or "UK businesses only"

WebMCP registration for browser agents

Beyond HTML attributes, you can programmatically register tools with the browser's model context using the WebMCP API. This is available in Chrome 146+ and provides a more structured way to expose form functionality to browser-based agents.

Registration component in Next.js

Create a client component that registers your contact form as a tool. This runs once when the page loads and makes the tool available to any AI agent operating in the browser:

// components/web-mcp-registration.tsx
"use client";

import { useEffect } from "react";

export function WebMCPRegistration() {
  useEffect(() => {
    const nav = navigator as any;
    if (!nav.modelContext?.addTool) return;

    nav.modelContext.addTool({
      name: "contact_form",
      description:
        "Submit an inquiry to the team. " +
        "Accepts name, email, company (optional), and message.",
      handler: async (params: {
        name: string;
        email: string;
        company?: string;
        message: string;
      }) => {
        const res = await fetch("/api/contact", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(params),
        });
        const data = await res.json();
        return data;
      },
    });
  }, []);

  return null;
}

Import this component in your root layout so it runs on every page:

// app/layout.tsx
import { WebMCPRegistration } from "@/components/web-mcp-registration";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <WebMCPRegistration />
        {children}
      </body>
    </html>
  );
}

Honeypot spam protection

CAPTCHAs are terrible for both user experience and AI agent interaction. They actively block legitimate agents. The honeypot pattern is a far better approach: it is invisible to both humans and legitimate AI agents, but catches automated spam bots effectively.

How honeypots work

You add a hidden form field that is invisible to human users via CSS (not type="hidden"). Legitimate users and AI agents leave this field empty because they either cannot see it or understand it is not a real field. Spam bots, which blindly fill in every field they find, will populate the honeypot. On the server, you check: if the honeypot field has a value, the submission is spam.

HTML implementation

Add the honeypot field to your form:

<!-- Honeypot field - hidden from humans and AI agents -->
<div style="position: absolute; left: -9999px;" aria-hidden="true">
  <label for="website">Website</label>
  <input
    type="text"
    id="website"
    name="website"
    tabindex="-1"
    autocomplete="off"
  />
</div>

Key implementation details:

• Use position: absolute; left: -9999px; to hide the field visually. Do not use display: none because some sophisticated bots skip fields with display: none.
• Add aria-hidden="true" so screen readers and accessibility tools skip it.
• Add tabindex="-1" so keyboard users cannot tab into it.
• Add autocomplete="off" so browsers do not auto-fill it.
• Use a tempting field name like website, url, or phone2. Spam bots are attracted to these common field names.

Server-side honeypot validation

In your API route, check the honeypot field before processing the submission. Return a 200 response even for rejected spam so the spammer cannot detect the honeypot:

// app/api/contact/route.ts
export async function POST(req: NextRequest) {
  const body = await req.json();

  // Honeypot check - if this field has a value, it is spam
  if (body.website) {
    // Return 200 to not alert the spammer
    return NextResponse.json({ success: true });
  }

  // Continue with legitimate submission processing...
}

Additional spam protection layers

Honeypots catch most spam, but you can add additional layers without affecting AI agents:

• Rate limiting: Limit submissions from the same IP to 5 per hour using Vercel's x-forwarded-for header or a counter in your database.
• Time-based validation: Record when the page loaded and reject submissions that arrive within 2 seconds. Humans cannot fill a form that fast, and this does not affect AI agents that take time to compose their messages.
• Input length validation: Reject messages under 10 characters or over 10,000 characters.
• Email format validation: Check that the email address has a valid format and a real domain with a DNS MX record check.

Server-side form handling in Next.js

Your API route needs to handle both traditional form submissions from browsers and JSON payloads from AI agents. Here is a complete, production-ready implementation.

Complete API route

// app/api/contact/route.ts
import { NextRequest, NextResponse } from "next/server";
import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);

// CORS headers for cross-origin agent requests
const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "POST, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization",
};

export async function OPTIONS() {
  return NextResponse.json({}, { headers: corsHeaders });
}

export async function POST(req: NextRequest) {
  try {
    // Parse body - handle both JSON and form-encoded
    let body: Record<string, string>;
    const contentType = req.headers.get("content-type") || "";

    if (contentType.includes("application/json")) {
      body = await req.json();
    } else if (contentType.includes("form")) {
      const formData = await req.formData();
      body = Object.fromEntries(formData.entries()) as Record<string, string>;
    } else {
      body = await req.json();
    }

    // Honeypot check
    if (body.website) {
      return NextResponse.json(
        { success: true, message: "Thank you for your inquiry." },
        { headers: corsHeaders }
      );
    }

    // Validate required fields
    const { name, email, message, company } = body;

    if (!name || typeof name !== "string" || name.trim().length === 0) {
      return NextResponse.json(
        { error: "Name is required" },
        { status: 400, headers: corsHeaders }
      );
    }

    if (!email || typeof email !== "string" || !email.includes("@")) {
      return NextResponse.json(
        { error: "Valid email address is required" },
        { status: 400, headers: corsHeaders }
      );
    }

    if (!message || typeof message !== "string" || message.trim().length < 10) {
      return NextResponse.json(
        { error: "Message must be at least 10 characters" },
        { status: 400, headers: corsHeaders }
      );
    }

    // Send email notification
    await resend.emails.send({
      from: "Website <notifications@yourdomain.com>",
      to: ["hello@yourdomain.com"],
      subject: `New inquiry from ${name.trim()}`,
      html: `
        <h2>New Contact Form Submission</h2>
        <p><strong>Name:</strong> ${name.trim()}</p>
        <p><strong>Email:</strong> ${email.trim()}</p>
        ${company ? `<p><strong>Company:</strong> ${company.trim()}</p>` : ""}
        <p><strong>Message:</strong></p>
        <p>${message.trim()}</p>
      `,
    });

    return NextResponse.json(
      {
        success: true,
        message: "Thank you for your inquiry. We will respond within 24 hours.",
      },
      { headers: corsHeaders }
    );
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to process your inquiry. Please try again." },
      { status: 500, headers: corsHeaders }
    );
  }
}

Response format for AI agents

The JSON response structure matters for AI agents. Always return a success boolean so the agent knows whether the submission worked, a message string the agent can relay back to the user, and an error string with specific details if validation fails. This allows agents to provide clear feedback to the user they are acting on behalf of.

Input sanitisation

Always sanitise user input before storing or sending via email to prevent XSS and injection attacks:

function sanitizeInput(input: string): string {
  return input
    .trim()
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#x27;")
    .slice(0, 5000); // Limit length
}

Email notification via Resend

Resend is the simplest transactional email service for Next.js applications. It integrates in under five minutes and handles email delivery reliably with a generous free tier.

Setup steps

1. Create a Resend account at resend.com and verify your sending domain by adding the DNS records they provide (SPF, DKIM, DMARC).
2. Generate an API key from the Resend dashboard.
3. Add the API key as RESEND_API_KEY in your Vercel environment variables. Never hardcode it.
4. Install the SDK: npm install resend

Sending the notification email

The API route example above includes the Resend integration. The key call is straightforward:

await resend.emails.send({
  from: "Website <notifications@yourdomain.com>",
  to: ["hello@yourdomain.com"],
  subject: `New inquiry from ${name}`,
  html: `<p>${message}</p>`,
});

For richer notification emails, use React Email templates that render to HTML. This gives you a well-designed email with consistent branding that you can maintain as a React component.

Schema.org ContactPoint structured data

Schema.org markup helps search engines and AI agents understand your contact information at a structured level. The ContactPoint schema type provides machine-readable contact details that agents can extract and use without parsing your HTML.

Organization with ContactPoint

Add this JSON-LD to your homepage or contact page:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://yourdomain.com",
  "contactPoint": [
    {
      "@type": "ContactPoint",
      "contactType": "sales",
      "email": "hello@yourdomain.com",
      "url": "https://yourdomain.com/contact",
      "availableLanguage": ["English"],
      "areaServed": "GB"
    },
    {
      "@type": "ContactPoint",
      "contactType": "customer service",
      "email": "support@yourdomain.com",
      "url": "https://yourdomain.com/support"
    }
  ]
}
</script>

ContactPage schema

Mark the contact page itself with the ContactPage schema type so search engines and agents understand this is the primary contact point:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "ContactPage",
  "name": "Contact Us",
  "description": "Get in touch for project inquiries, quotes, and support.",
  "url": "https://yourdomain.com/contact",
  "mainEntity": {
    "@type": "Organization",
    "name": "Your Company",
    "email": "hello@yourdomain.com",
    "contactPoint": {
      "@type": "ContactPoint",
      "contactType": "sales",
      "email": "hello@yourdomain.com"
    }
  }
}
</script>

What AI agents extract from ContactPoint data

When an AI agent processes your structured data, it extracts the contact type (sales, support, billing) to route the user's request correctly, the email address as a fallback, the available language to match the user's preference, the area served for geographic relevance, and the URL to navigate to if programmatic submission is not possible.

Making forms discoverable through the MCP manifest

For server-side AI agents that interact via your MCP server, list the contact endpoint as a tool in your mcp.json manifest. This file lives at public/mcp.json and is the machine-readable directory of all tools your site exposes:

// public/mcp.json
{
  "name": "your-product",
  "description": "Your product description",
  "endpoint": "https://yourdomain.com/api/mcp",
  "protocol": "mcp-http",
  "auth": { "type": "none" },
  "tools": [
    {
      "name": "submit_contact_form",
      "description": "Submit an inquiry. Requires name, email, and message.",
      "scope": "write",
      "inputSchema": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Full name" },
          "email": { "type": "string", "description": "Email address" },
          "company": { "type": "string", "description": "Company (optional)" },
          "message": { "type": "string", "description": "The inquiry" }
        },
        "required": ["name", "email", "message"]
      }
    }
  ]
}

See the MCP Server Guide for the full server implementation.

Listing the contact endpoint in llms.txt

Your llms.txt file should document the contact endpoint so AI crawlers and agents know it exists and how to use it:

# Contact
- Contact form: https://yourdomain.com/contact
- API endpoint: POST https://yourdomain.com/api/contact
  - Content-Type: application/json
  - Body: { "name": "string", "email": "string", "message": "string" }
  - Response: { "success": boolean, "message": "string" }
  - No authentication required

Testing your contact form for agent readiness

After implementing your contact form, verify that it works for both humans and AI agents using these test methods.

Test via curl (simulating an AI agent)

# Test successful submission
curl -X POST https://yourdomain.com/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Agent",
    "email": "test@example.com",
    "message": "This is a test submission from an AI agent."
  }'

# Test honeypot rejection (should return 200 silently)
curl -X POST https://yourdomain.com/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spam Bot",
    "email": "spam@example.com",
    "message": "Buy cheap pills",
    "website": "http://spam.com"
  }'

# Test validation errors
curl -X POST https://yourdomain.com/api/contact \
  -H "Content-Type: application/json" \
  -d '{ "name": "", "email": "bad", "message": "hi" }'

Verification checklist

1. Submit via browser and verify the email notification arrives.
2. Submit via curl with JSON payload and verify the response.
3. Test the honeypot by submitting with the honeypot field populated.
4. Test validation by submitting with missing or invalid fields.
5. Inspect the HTML source and confirm data-mcp-tool attributes are present.
6. Validate your Schema.org markup with Google's Rich Results Test.
7. Test CORS by sending a request from a different origin. See the CORS Headers Guide.
8. Run an AgentReady scan to verify agent discoverability.

Frequently Asked Questions

Why do contact forms matter for AI agents?

AI agents need structured, discoverable action endpoints to interact with websites on behalf of users. A well-built contact form with proper HTML semantics, data-mcp-tool attributes, and a JSON API endpoint allows agents to submit inquiries, book meetings, and request quotes programmatically. Without these, your site is a read-only brochure to AI agents, and you miss out on leads from the fastest-growing referral channel on the web.

What is the data-mcp-tool attribute?

The data-mcp-tool attribute is a custom HTML attribute added to interactive elements like forms and buttons that tells AI agents what action the element performs. It is part of the WebMCP protocol used by browser-based AI agents in Chrome 146+. For example, data-mcp-tool="contact_form" with data-mcp-description="Submit an inquiry to the sales team" helps agents understand and interact with your forms without guessing what the form does.

How do I protect my contact form from spam while keeping it accessible to AI agents?

Use a honeypot field pattern: add a hidden form field that real users and legitimate AI agents will leave empty, but automated spam bots will fill in. On the server side, reject any submission where the honeypot field has a value. Return a 200 response even for rejected submissions so spammers cannot detect the honeypot. This approach is invisible, requires no CAPTCHA, and does not block legitimate agent traffic.

Should my contact form have a JSON API endpoint or just a traditional form action?

Both. A traditional HTML form with a proper action attribute works for browsers and browser-based agents. A JSON API endpoint at the same path allows server-side AI agents to submit structured data programmatically with proper request and response handling. In Next.js, a single API route can handle both application/x-www-form-urlencoded and application/json payloads by checking the Content-Type header.

What Schema.org markup should I add to my contact page?

Add ContactPoint schema to your Organization structured data, including contactType (e.g. "sales", "customer service"), email, and availableLanguage. Also add a ContactPage schema type to the page itself. This helps AI agents and search engines understand how to reach your business without parsing the HTML form directly.

How do I send email notifications when a form is submitted?

Use a transactional email service like Resend, SendGrid, or Postmark. In Next.js, call the email API from your form handler API route after validating the input. Resend is the simplest option: install the SDK with npm install resend, configure your API key as an environment variable, and call resend.emails.send() with the form data formatted as an HTML email.

Can AI agents fill in and submit HTML forms directly?

Yes. Browser-based AI agents like those in Chrome 146+ can interact with HTML forms using the WebMCP protocol. They read data-mcp-tool and data-mcp-description attributes to understand form purpose, then fill in fields using label associations and name attributes. Server-side agents bypass the form entirely and call the JSON API endpoint directly.

How do I make my contact form discoverable to AI agents?

Four methods, each targeting different types of agents: (1) Add data-mcp-tool attributes to the form element for browser agents. (2) Register the form as a WebMCP tool using navigator.modelContext.addTool() for Chrome agents. (3) List the contact endpoint in your MCP server manifest at /mcp.json for server-side agents. (4) Add ContactPoint schema markup to your page for search engine and AI crawler comprehension.