Talkform
Menu
Docs

MCP

Use local config tools or authenticated hosted handoff tools through MCP.

Talkform exposes a local configuration surface and a hosted project handoff surface. They have different ownership and retention boundaries.

Claude connector with account access

Connect to https://www.talkform.ai/api/mcp using Streamable HTTP. Discovery and public template/draft tools work without sign-in. A private project operation prompts for Talkform sign-in and OAuth consent. OAuth access is limited to the signed-in person's human-owned projects and the granted handoffs:read, handoffs:write, and handoffs:delete permissions. Identity-only consent never grants project access. Tokens must be issued by https://clerk.talkform.ai for this exact MCP resource.

Create a project at /dashboard before using account tools. If there is one owned project, it is selected automatically. With multiple projects, include projectId on create_handoff, configure_webhook, get_webhook, or delete_webhook; the response supplies the owned project IDs when selection is needed. Reads and deletion by handoff ID derive and verify project ownership. No project API key is created by OAuth sign-in. A revoked token or permission cannot access private data.

The full connector exposes 11 tools: three template/draft tools, machine workspace registration, four handoff tools, and three webhook tools. MCP prepares configurations and links; optional respondent voice interviews run separately on Talkform.

Public-only endpoint

For template review and form preparation without an account, connect to https://www.talkform.ai/api/mcp/public using Streamable HTTP and no authentication. This profile exposes exactly three read-only tools: talkform.list_templates, talkform.get_template, and talkform.prepare_form. They return public templates or a validated draft in the tool response; they do not publish a form, create a project, collect respondent answers, configure a webhook or generate audio.

For example, talkform.get_template accepts {"id":"customer-feedback"}. talkform.prepare_form accepts a title and a bounded fields array with each field's id, label, type, required flag, promptTitle and promptDetail. No reviewer account or private credentials are needed for this profile. The full hosted endpoint above adds account operations and OAuth sign-in; this public-only endpoint remains available for clients that only need drafts.

Autonomous agent registration

An agent can register a machine workspace anonymously with talkform.register_agent or POST /api/v1/agents/register. The input accepts an optional name, an optional environment (production or test, defaulting to production), and a fresh UUIDv4 idempotency key:

{
  "name": "research-agent",
  "environment": "production",
  "idempotencyKey": "8d7e6f5a-4b3c-42d1-9e8f-7a6b5c4d3e2f"
}

The response contains registration, project, key, secret, limits, and urls. It marks the registration as ownerKind: machine, verifiedHuman: false, and voiceEligible: true; the initial limit is 10 handoffs per day. Save the one-time secret in the MCP client's server-side secret configuration. No email address or Clerk user is created. Reusing the same idempotency key, even after a network change, returns 409 registration_exists without replaying the secret; use a fresh key only for a new registration, within the limit of 3 registrations per address per day.

An optional signed-in human can claim the machine workspace with its project key. Claiming enables the human-owned project limit and optional voice; it does not expose or rotate the machine secret.

Hosted project tools

Claude uses the account OAuth flow described above. API-key clients can instead register a machine workspace with talkform.register_agent or create a project and key in /dashboard, then configure that project key in the client's server settings:

Authorization: Bearer tfk_...

Keep the Bearer value in the MCP client's server-side secret configuration. Do not put it in a prompt, browser page, or tool argument.

The project key scopes every handoff read, write, and delete. Dashboard-created keys currently carry all three handoff scopes; per-key scope selection is not exposed in the dashboard. Respondents do not need an account. The hosted project tools are:

  • talkform.create_handoff with { "config": <AudioformConfig>, "idempotencyKey": "..." }. Put the human question in each field's promptTitle. Set config.branding.fromName, branding.purpose, optional branding.logoUrl, and hex theme colors so the respondent page is about the product, not Talkform.
  • talkform.get_handoff with { "id": "..." }
  • talkform.get_result with { "id": "..." }
  • talkform.delete_handoff with { "id": "..." }

create_handoff returns an expiring respondent URL. Send that link to a person. The person answers, reviews the structured values, and explicitly submits them. get_result returns the reviewed structured result once submission is complete.

Complete hosted walkthrough

  1. Ask the authenticated hosted server to create one handoff. Reuse this exact idempotencyKey if the tool call must be retried:
talkform.create_handoff
{
  "config": {
    "id": "mcp-product-feedback",
    "title": "Product feedback",
    "branding": {
      "fromName": "My Forever Songs",
      "purpose": "2 min product feedback"
    },
    "mode": "text",
    "fields": [
      {
        "id": "desiredOutcome",
        "label": "Desired outcome",
        "type": "long_text",
        "required": true,
        "promptTitle": "What outcome are you trying to achieve?",
        "promptDetail": "Ask for one concrete outcome in the respondent's own words."
      }
    ]
  },
  "idempotencyKey": "feedback-request-2026-09-10-001"
}

The result contains id, respondentUrl, status, expiresAt, title, purpose, fromName, shareText, mode, and voiceEligible. Paste shareText to the user who will send the link. An agent must not invent answers or submit on the person's behalf. Omitted mode is voice. Set mode: "text" only for a written interview.

  1. After the person opens the link, answers, reviews, and explicitly submits, check status using the returned ID:
talkform.get_handoff
{ "id": "11111111-1111-4111-8111-111111111111" }

If status is pending, wait at least 10 seconds before checking again. Once it is completed, retrieve the reviewed result:

talkform.get_result
{ "id": "11111111-1111-4111-8111-111111111111" }

The returned JSON includes canonical completion, fields, and metadata.mode. Hosted transcript is [] and summary is "". Receiving the tool result proves Talkform served it to the authenticated project; it does not prove a downstream action occurred.

  1. When the user explicitly wants the hosted content removed, call:
talkform.delete_handoff
{ "id": "11111111-1111-4111-8111-111111111111" }

Deletion is permanent. The tool returns { "id": "...", "deleted": true } and is stable when the authorized project repeats it.

Poll talkform.get_result no more often than every 10 seconds. A pending or expired handoff produces a corresponding MCP tool error; the underlying REST result endpoint returns 409 Conflict or 410 Gone. Links and completed-result access last 7 days. Machine workspaces start at 10 hosted handoffs per day; human-owned projects can reach 100 per day per project after claim. New handoff creation also observes shared fair-use capacity of 1,000 per UTC day. Voice is available under shared limits.

Results contain the reviewed structured fields and response mode. Talkform does not retain or return a hosted transcript or generated summary. A successful get_result means the authenticated project received the response from Talkform; it does not prove downstream processing.

Signed completion webhooks can be managed with talkform.configure_webhook (url, optional projectId, write permission), talkform.get_webhook (optional projectId, read permission), and talkform.delete_webhook (optional projectId, write permission). Configuration returns a signing secret once; keep it in server-side secret storage. Deleting a webhook disables delivery and cancels outstanding attempts. Poll from the project worker when no webhook is configured and keep downstream actions idempotent. Reuse create_handoff idempotency keys for retries.

What agents can do without sign-in

The same public endpoint can expose these anonymous draft tools without a project key:

  • talkform.list_templates
  • talkform.get_template
  • talkform.prepare_form

It can also expose talkform.register_agent, which creates a machine workspace and returns a one-time project secret. Registration is the only anonymous tool that creates a hosted account-owned resource; the draft tools remain stateless.

talkform.prepare_form is stateless. An agent can generate and validate a reviewable form draft anonymously. Creating a private respondent link, checking its status, retrieving reviewed answers, or deleting it requires OAuth account authorization or a project key and the hosted tools above. Anonymous draft preparation does not persist a handoff, submit a source form, deliver a webhook, or retain form drafts, conversations, transcripts, answers, or tool payloads.

Install the local configuration server

For schemas, templates, and config validation in a local stdio MCP process, run Node.js 20 or newer:

npx --yes @talkform/mcp@latest

Or install exact-version MCP configuration for Claude, Codex, and Cursor:

npx --yes @talkform/cli@latest install --all

This local package does not expose the remote hosted handoff tools or capture microphone audio.

Local tools and resources

Tools:

  • talkform.list_templates
  • talkform.get_config_schema
  • talkform.validate_config

Resources:

  • talkform://schema/config
  • talkform://schema/session-result
  • talkform://templates
  • talkform://template/{id}