# PortForm — full agent guide > PortForm is a form-to-email backend for static and any-framework sites. Point an HTML form's `action` at PortForm's endpoint with an access key; PortForm stores the submission, filters spam, emails it to you, and forwards it to your integrations. No server code and no JavaScript are required on your site. > > This document is the comprehensive, machine-readable guide for AI agents and developers. For the concise version see https://www.portform.co/llms.txt. For the human-facing agent page see https://www.portform.co/for-agents. ## Two ways an agent works with PortForm 1. Anonymous sandbox — no account and no token. An agent can build, wire, test, and verify a form BEFORE anyone signs up, then hand a claim URL to the human, who signs in and keeps the form. 2. Authenticated MCP — after the human has an account and mints a token, an agent connects to PortForm's MCP server to create and manage forms and read submissions on an ongoing basis. The sandbox is the pre-signup workflow. MCP is authenticated ongoing management. They are separate: the sandbox never needs an MCP token, and MCP never accepts anonymous access. ## What PortForm is - A hosted form backend. A form POSTs to one endpoint with an access key; PortForm validates, stores, filters spam, and emails the destination inbox, then fires any integrations. - Access keys are public routing IDs (like a mailto: address), not secrets. Protection is quota, per-key rate limiting, spam filtering, and optional domain restriction (Pro). - Every submission is stored before anything else, so a failed email never loses the message. ## Core submit endpoint - `POST https://app.portform.co/api/submit` (with `https://app.portform.co/api/v1/submit` as the versioned form; `/api/submit` is a permanent alias). - Accepts URL-encoded, multipart, or JSON bodies. Works from a zero-JavaScript plain HTML `
`. - Required: an `access_key` field. Include the hidden `botcheck` honeypot field and leave it empty on real submissions. Example (form-encoded): ``` curl -X POST https://app.portform.co/api/submit \ -F access_key=YOUR_ACCESS_KEY \ -F name=Ada \ -F email=ada@example.com \ -F message="Hello from an agent" \ -F botcheck= ``` ## Anonymous sandbox workflow Endpoint: `POST https://app.portform.co/api/v1/public/sandboxes` — anonymous, CORS-open, no token. Request body (both fields optional, JSON or form-encoded): - `label` — a name for the form (defaults to "Agent sandbox form"). - `destination_email` — where a claimed form would deliver (defaults to a placeholder; sandbox test submissions are stored but never emailed). The 201 response provides everything the next steps need: - `sandbox` — id, status, expires_at, test_submissions_used / remaining / max, claimed - `form` — id, label, destination_email - `access_key` — the id to POST submissions with (the form id and the access key are the same value) - `submit_url` — where to POST test submissions - `status_url` — GET to verify receipt - `claim_url` — the single-use URL to hand the human - `token` — the one-time claim token, returned once and never again (embedded in claim_url) - `snippets` — ready-to-paste HTML and curl - `test` — how many test submissions are allowed and how to send them - `next` — ordered next steps (wire, test, verify, claim) Lifecycle: create → wire → test → verify → claim. 1. CREATE — POST to the sandbox endpoint; read back access_key, submit_url, status_url, claim_url. 2. WIRE — paste snippets.html into the site, or POST the form fields to submit_url with the access_key. 3. TEST — send up to 5 test submissions to prove it works end to end. 4. VERIFY — GET status_url to confirm the submissions were received. 5. CLAIM — give the human claim_url. They sign in and the sandbox becomes their permanent form — same id, same submit URL. ## Sandbox limits - Up to 5 test submissions per sandbox, then it must be claimed. - A sandbox lives 24 hours if unclaimed, then expires and is swept. - Up to 3 sandboxes may be created per IP per 10 minutes. - Sandbox test submissions are stored but never emailed (the destination is unverified), and cost no account quota. - These are the only sandbox limits. The sandbox has no other capabilities — it is a throwaway form, not an account. ## Submit URL and status URL - submit_url is the same core submit endpoint (`https://app.portform.co/api/submit`); the sandbox access_key routes to the sandbox form. - status_url (`https://app.portform.co/api/v1/public/sandboxes/`) returns safe public metadata only: status, expiry, test-submission counts, whether any were received, and whether it is claimed. It never returns the token, account ids, or submission content. ## Claim workflow - The creation response returns a one-time claim token inside claim_url. Only its hash is stored; the plaintext is shown once. - The agent hands claim_url to the human. The human opens it, signs in, and the sandbox's access key is transferred to their account — same id, same submit URL — with its test history reassigned. - Claiming is single-use and race-safe: a replayed or expired link cannot claim. - Agents must never print, echo, log, or commit the claim token beyond handing the human the claim URL. ## Authenticated MCP After the human has an account, an agent can connect to PortForm's MCP server to manage forms and read submissions. - Endpoint: `https://app.portform.co/api/v1/mcp` (Streamable HTTP; one JSON-RPC 2.0 message per POST). There is no stdio package to install. - MCP protocol version: 2025-06-18. - Authentication: an `Authorization: Bearer pf_...` workspace token. Anonymous access is not permitted — every request, including initialize and tools/list, is authenticated. - Role-gated: a token is bound to the workspace and to the user who minted it, and that role is re-read on every request. A token can never exceed its user's workspace role, and reaches only the tools below. Billing, members, linked emails, and integrations are not available over MCP. ### MCP tools Eight tools are registered. Their full JSON Schemas are served authoritatively by tools/list on the live server; concise purposes: - list_forms: List the forms on the authenticated workspace. - get_form: Read one form’s configuration by id. - create_form: Create a form; returns its id, which is the access key to POST submissions with. - update_form: Update an existing form’s configuration. - list_submissions: List submissions for a form. - get_submission: Read one submission by id. - test_submission: Send one real test submission to prove delivery end to end (costs one submission of the 30-day quota on a live form; free on a test-mode form). - diagnose: Statically lint form markup and report wiring problems before it ships. ## Existing agent catalog PortForm publishes setup for 15 coding agents. The server is registered as "portform" in every client config, and file-based configs reference the `PORTFORM_TOKEN` environment variable rather than inlining the token. Setup shape varies by client (one command, a config file, or the agent's own settings UI); a few agents cannot present a bearer token and use the copy-the-prompt path instead. - Claude Code (One command) - Codex (One command) - Gemini CLI (One command) - VS Code (One command) - Cursor (Config file) - Windsurf (Config file) - Cline (Config file) - Roo Code (Config file) - opencode (Config file) - Antigravity (Config file) - Devin (Set up in Devin) — Needs the Manage MCP Servers permission in your Devin organisation. - v0 (Set up in v0) — v0 uses the tools while it generates. The app it produces does not get MCP access of its own. - Replit Agent (Set up in Replit) - Copilot coding agent (Set up in GitHub) — Needs repository admin access, and the token has to be stored as a COPILOT_MCP_ secret. - Bolt (Prompt only) — Bolt’s custom MCP settings only offer an OAuth client id and secret — there is no field for an Authorization header, so it cannot present a PortForm token. Copy the prompt instead. The canonical, per-agent setup instructions are generated from lib/agents.ts and shown at https://www.portform.co/for-agents and in the dashboard's connect flow. Do not hardcode a second setup; use the generated one. ## Agent setup concept - One MCP server URL (`https://app.portform.co/api/v1/mcp`), one bearer token, registered under the name "portform". - Never write the token into a file committed to a repository. File-based configs reference `PORTFORM_TOKEN` (or the client's own secret prompt); only configs stored outside the repo or typed into a web UI may carry the value. - Placeholders only in shared documentation, e.g. YOUR_PORTFORM_TOKEN, YOUR_CLAIM_TOKEN, or ${env:PORTFORM_TOKEN}. ## AI prompt and MCP-first flows PortForm supports two "build with AI" flows, both driven from lib/snippet.ts: - Prompt flow — a ready-to-paste prompt makes an AI assistant write the form markup wired to an existing access key. The form already exists; the prompt carries its key and the honeypot. - MCP-first flow — an agent already connected to the MCP server provisions the form itself: it calls list_forms, create_form, diagnose, then test_submission once, and reads the access key out of create_form. ## Security and token handling - Access keys are public by design; leaking one is not a security incident. The real controls are quota, rate limiting, spam filtering, and optional domain restriction. - MCP tokens (`pf_...`) and sandbox claim tokens (`pfsbx_...`) ARE secrets. Never print, log, commit, or embed them in shared docs. Use environment variables and placeholders. - Sandbox test submissions are stored but never emailed; the endpoint is not an open relay. ## Limitations and retention - Free tier: a hard cap of 300 submissions per rolling 30 days; over-limit submissions are rejected with a clear error, never silently dropped or auto-billed. - Submissions, request logs, and delivery logs are retained for 30 days, then purged. - Access keys are public and are not a security boundary; domain restriction is a convenience control, not authentication. ## Important distinctions - Sandbox = anonymous, temporary, pre-signup. No token. Limited to 5 test submissions and 24 hours. - MCP = authenticated, ongoing. Requires a `pf_...` bearer token and a real account. Role-gated to the eight tools above. - The submit endpoint is public and permanent; the sandbox and MCP are two different ways to get a form onto it. ## Links - Home: https://www.portform.co - Agent page: https://www.portform.co/for-agents - Concise machine-readable spec: https://www.portform.co/llms.txt - Developer docs: https://www.portform.co/docs - MCP endpoint (not browsable; the live MCP server): https://app.portform.co/api/v1/mcp - Pricing: https://www.portform.co/pricing - Live demo (no signup): https://www.portform.co/demo - Sign up: https://app.portform.co/signup