Postbox as an MCP Server — AI Clients Meet Structured Data Collection

If you’ve used our REST API or curl endpoints, you already know Postbox works with non-browser clients. But those approaches still require the client to know something upfront — a URL, a schema, what fields to send. The client has to be told where to go and what to do.

With MCP, the client figures it out on its own.

What MCP is

Model Context Protocol is an open standard for AI agents to discover and invoke tools programmatically. Instead of hardcoding API calls, an MCP client connects to a server, asks “what can you do?”, and gets back a list of tools with typed parameters and descriptions.

Think of it as service discovery for AI. The agent doesn’t need documentation. It doesn’t need a human to describe the endpoints. It connects, reads the tool definitions, and starts working.

Anthropic created the protocol. Claude Desktop, Claude Code, Cursor, Windsurf, and a growing list of AI clients support it natively. If your AI tool supports MCP, it can talk to Postbox directly.

Postbox has a built-in MCP server

Every Postbox account with a Pro plan gets access to an MCP server at the /mcp endpoint. It uses Streamable HTTP transport — the modern, stateless approach that works over standard HTTP without requiring WebSocket connections or server-sent events.

This isn’t a third-party integration or a plugin. The MCP server is part of Postbox. It reads from the same database, enforces the same schemas, applies the same rate limits. When an AI agent connects to your Postbox MCP server, it’s talking to Postbox directly.

Rate limit: 30 requests per minute per user. Enough for any reasonable agent workflow, strict enough to prevent abuse.

What the agent can do

Once connected, an MCP client discovers ten tools across two categories.

Read-only tools — available to all MCP connections:

• list_forms — returns all forms for the authenticated user
• get_form — returns a specific form including its full schema definition (field names, types, required flags)
• list_submissions — returns submissions with filtering (inbox, spam, or all) up to 50 at a time
• get_submission — returns a single submission with all its data
• get_dashboard_stats — returns aggregate stats across all forms

Intelligence tools — Pro plan features powered by AI:

• translate_submission — translates a submission into a target language (how translation works)
• analyze_spam — runs spam analysis on a submission (how spam filtering works)
• draft_reply — generates a reply to a submission with optional custom instructions (how smart replies work)
• summarize_submissions — produces a summary across submissions for a form

Every tool is tenant-isolated. An MCP client authenticated as your user can only access your forms, your submissions, your stats. There is no way to read another user’s data, even if the agent tries.

MCP vs. REST API — the real difference

We wrote about using agents with the REST API. That works. You give the agent a URL and a bearer token, and it can submit data. But there’s a hierarchy of agent integration, and it matters.

REST API: “Here’s a URL, figure it out.” The agent needs to know the endpoint, the HTTP method, the content type, and the field schema. A human provides all of this. The agent is basically a fancy HTTP client executing instructions it was given.

Self-documenting endpoints: “Ask the URL what it expects.” Postbox supports this — hit a form endpoint with a GET request and it returns the schema. Better. The agent can discover field definitions on its own. But it still needs the URL, and it still needs to know to make that GET request in the first place.

MCP: “The agent discovers everything on its own.” The agent connects to one server URL. It gets back a list of every tool available. It can list forms, read schemas, submit data, query results, run analysis — all through tool discovery. No hardcoded URLs. No documentation to read. No human in the loop telling it what to call.

This is the highest level of agent integration we offer. It’s the difference between giving someone a map and dropping them in a self-driving car.

How to connect

Add Postbox as an MCP server in your client’s configuration. For Claude Desktop, that’s in your MCP settings file:

{
  "mcpServers": {
    "postbox": {
      "url": "https://usepostbox.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

For Claude Code, add it via the CLI:

claude mcp add postbox \
  --transport http \
  https://usepostbox.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with your Postbox API key, which you can generate from your API Keys settings. That’s it. The client handles the rest — connecting, discovering tools, and making them available in conversation.

An example workflow

Here’s what happens when an MCP client connects to Postbox, step by step.

1. Connection. The client sends an initialize request to https://usepostbox.com/mcp. Postbox responds with server capabilities and the list of available tools.

2. Discovery. The agent sees ten tools with full parameter schemas. It now knows it can list forms, read submissions, draft replies, and everything else — without anyone telling it.

3. Schema reading. The agent calls list_forms to see what forms exist. It picks one and calls get_form to read the full schema — field names, types, required flags. Now it knows exactly what data structure the form expects.

4. Querying. The agent calls list_submissions with a filter for inbox-only submissions. It reads through recent submissions. It calls summarize_submissions to get a high-level overview.

5. Action. The agent calls draft_reply for a specific submission, providing custom instructions like “be concise and professional.” It calls translate_submission to translate a submission from Spanish to English.

All of this happens through tool calls. The agent never constructs a URL. It never parses a REST response format. It uses typed tool invocations with structured inputs and outputs.

Why this matters for the future

We wrote in our thesis that the entities submitting data are no longer just humans behind browsers. The same is true for the entities reading data. AI agents don’t just produce data — they consume it, analyze it, and act on it.

MCP is the protocol that makes this seamless. Instead of building custom integrations for every AI client, we expose a single MCP server and let the protocol handle discovery. Every MCP-compatible client — today and in the future — gets full access to Postbox’s capabilities without us writing a single line of integration code for each one.

The schema-first architecture we describe in why structured forms matter is what makes this work. Because every form has a typed schema, the MCP tools can describe exactly what data they expect. The agent doesn’t guess. It reads the schema, validates its own output, and submits clean data.

Dumb pipes can’t do this. An endpoint that accepts anything can’t tell an MCP client what it expects. Structure is what makes tool discovery useful.

Pricing

MCP access requires the Pro plan at $19/month or $199/year. The intelligence tools (translation, spam analysis, reply drafting, summarization) consume AI credits — included with Pro and metered beyond the monthly allowance.

The read-only tools (listing forms, reading submissions, getting stats) don’t consume AI credits. An agent can query your data all day within the rate limit at no additional cost.

Get started

If you’re already on Pro, your MCP server is live right now. Generate an API key, add the server to your MCP client, and start a conversation. The agent will discover your forms, read your schemas, and have the full picture within seconds.

If you’re on the free plan, upgrade to Pro to unlock MCP access alongside unlimited forms, unlimited submissions, and 500 AI credits per month.

Your forms are already structured. Your schemas are already typed. MCP just lets agents discover that on their own.