Formasty Beautiful Forms

A portable Agent Skills package for creating beautiful Formasty forms through the Formasty MCP server.

This repo is built for broad agent compatibility: Codex, Claude Code, OpenCode, Cursor, Windsurf, custom MCP agents, and any client that can read the open SKILL.md format. It contains instructions, references, marketplace metadata, and MCP configuration only. It does not include Formasty application source code.

What Agents Can Do With It

• Create production-ready Formasty forms from plain-English briefs.
• Choose correct field types, steps, microcopy, visual direction, and endings.
• Add tasteful images or creative backgrounds when they improve the form.
• Configure workflow variables, routes, matching rules, score rules, and multiple endings when available.
• Validate drafts before publishing.
• Avoid unsupported schema fields, stale image URLs, and duplicate drafts on retries.

Package Layout

formasty-beautiful-forms/
├── .codex-plugin/
│   └── plugin.json                 # Codex Marketplace plugin wrapper
├── .mcp.json                       # Formasty MCP server metadata
├── skills/
│   └── formasty-beautiful-forms/
│       ├── SKILL.md                # Canonical portable skill
│       ├── agents/openai.yaml      # OpenAI/Codex UI metadata
│       └── references/             # Design, image, and workflow guidance
├── assets/banner.png
├── LICENSE
└── README.md

The source of truth is:

skills/formasty-beautiful-forms/SKILL.md

Connection Requirements

Agents need Formasty access through one of these modes:

• Preferred: Formasty MCP OAuth.
• Fallback: a dedicated Formasty API key with only the required scopes.

MCP endpoint:

https://app.formasty.com/api/mcp

OAuth Setup For AI Agents

Agents should help the user complete OAuth instead of asking for passwords or long-lived secrets.

Recommended agent behavior:

1. Check whether a Formasty MCP server named formasty is configured.
2. If it is missing, ask the user to run the MCP add command for their client.
3. Ask the user to complete the OAuth login in their own terminal/browser.
4. Ask the user to run a connection test.
5. Continue only after the MCP tools are available.

For Hermes, the user can run:

hermes mcp add formasty \
  --url https://app.formasty.com/api/mcp \
  --auth oauth

hermes mcp login formasty
hermes mcp test formasty
hermes mcp list

Expected result:

• Browser opens to Formasty OAuth.
• User signs in to Formasty.
• User approves requested scopes.
• Hermes stores the OAuth token locally.
• hermes mcp test formasty succeeds.

If Hermes or another client returns 405 Method Not Allowed, that usually means the client is trying to use SSE/GET against Formasty's MCP endpoint. Formasty's MCP endpoint accepts JSON-RPC over POST / Streamable HTTP.

Use this troubleshooting response:

Formasty OAuth is available, but this MCP client appears to be using SSE. Please configure the Formasty MCP server as Streamable HTTP / JSON-RPC over POST, not SSE. If your client does not support Streamable HTTP yet, use a dedicated Formasty API key for this session or update the MCP client.

Do not claim authentication is complete until the agent can actually list Formasty MCP tools or successfully call a read-only tool such as listing workspaces.

API Key Fallback

If OAuth is unavailable in the user's MCP client, ask the user to create a dedicated Formasty API key with the minimum scopes needed for the task.

For creating and editing forms, request:

forms:read, forms:create, forms:update, forms:steps:write, forms:fields:write, forms:design:write, forms:logic:write

Add only when needed:

forms:publish       # only if the user wants the agent to publish
submissions:read    # only for response/reporting analysis

Security rules for agents:

• Do not ask the user to paste account passwords.
• Prefer OAuth whenever the MCP client supports it.
• If using an API key, ask the user to provide it through the agent/client's secret manager or environment-variable mechanism, not in public chat.
• Use the narrowest scopes required for the current task.
• Tell the user to revoke the key after one-off migration or demo work if it is no longer needed.

Install With Codex Marketplace CLI

When the repo is public/indexable, install as a plugin:

npx codex-marketplace add QuantumCoderSys/formasty-beautiful-forms --plugin --global

Or install just the standalone skill folder:

npx codex-marketplace add QuantumCoderSys/formasty-beautiful-forms/skills/formasty-beautiful-forms --skill --global

Install For Codex Manually

mkdir -p ~/.agents/skills
git clone https://github.com/QuantumCoderSys/formasty-beautiful-forms.git /tmp/formasty-beautiful-forms
cp -R /tmp/formasty-beautiful-forms/skills/formasty-beautiful-forms ~/.agents/skills/

Then restart Codex if the skill does not appear immediately.

Claude Code

Use the skill as a standard Agent Skills folder and configure the Formasty MCP server separately in Claude Code.

mkdir -p ~/.claude/skills
git clone https://github.com/QuantumCoderSys/formasty-beautiful-forms.git /tmp/formasty-beautiful-forms
cp -R /tmp/formasty-beautiful-forms/skills/formasty-beautiful-forms ~/.claude/skills/

If your Claude Code setup supports remote MCP servers, add Formasty as a Streamable HTTP MCP server:

Name: formasty
URL: https://app.formasty.com/api/mcp
Transport: streamable_http
Auth: OAuth preferred, API key fallback

OpenCode

Install the same skill folder into OpenCode's skills directory, or add this repository as a skill source if your OpenCode distribution supports skill repositories.

git clone https://github.com/QuantumCoderSys/formasty-beautiful-forms.git /tmp/formasty-beautiful-forms
# Copy /tmp/formasty-beautiful-forms/skills/formasty-beautiful-forms
# into your OpenCode skills directory.

Then configure the Formasty MCP server using the MCP settings supported by your OpenCode version.

Cursor, Windsurf, And Other IDE Agents

Use one of these integration modes:

• Point the agent at skills/formasty-beautiful-forms/SKILL.md as a reusable instruction file.
• Copy the full skills/formasty-beautiful-forms/ folder into the agent's skills directory if it supports the Agent Skills standard.
• Configure Formasty MCP separately using https://app.formasty.com/api/mcp.

Generic MCP Agents

For any custom agent, load the skill folder as procedural instructions and connect the remote MCP server.

Minimal MCP metadata:

{
  "mcpServers": {
    "formasty": {
      "type": "streamable_http",
      "url": "https://app.formasty.com/api/mcp"
    }
  }
}

Then prompt the agent with:

Use the Formasty Beautiful Forms skill to create a premium school admissions form with student details, parent info, document upload, and a trustworthy visual style.

Example Prompts

Use Formasty Beautiful Forms to create a polished lead capture form for a boutique interior design studio. Make it elegant, short, and conversion-focused.

Use Formasty Beautiful Forms to build a personality quiz for founders that recommends one of three productivity systems. Use matching rules and multiple ending screens.

Use Formasty Beautiful Forms to redesign my existing event registration form so it feels premium, has better microcopy, and includes a clear post-registration ending screen.

Use Formasty Beautiful Forms to create a paid workshop registration form with attendee details, session choice, and payment setup if the workspace supports it.

Marketplace Status

The package is ready for marketplace submission as a Codex plugin because it includes:

• .codex-plugin/plugin.json
• .mcp.json
• skills/formasty-beautiful-forms/SKILL.md
• repo banner/screenshot assets
• MIT license

Public marketplace indexing generally requires the GitHub repository to be public. This repository is currently private until you choose to make it public.

License

MIT. See LICENSE.