Parzley MCP Server

Exposes the Parzley AI Form Filling Agent API as an MCP server — enabling Claude Desktop, Claude.ai, and any MCP-compatible client to interact with Parzley natively via natural language.

Requires Python 3.13+ (see pyproject.toml).

---

Quick start

1. Install the package

From the repository root (use a virtual environment):

pip install .

Or with uv:

uv sync

Dependencies: fastmcp, httpx (declared in pyproject.toml).

If you change pyproject.toml dependencies, run uv lock and commit the updated uv.lock. Hosts that run uv sync --locked (e.g. Railway Railpack) will fail until the lockfile matches.

---

Connecting to Claude Desktop (local / stdio)

The server entry point is main.py (not the legacy commented parzley_mcp_server.py).

Add the following to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "parzley": {
      "command": "python",
      "args": ["C:/path/to/Parzley_MCP/main.py"]
    }
  }
}

Note: Use the full path to your clone of this repo. command must be a Python 3.13+ interpreter (where python / which python3). On Windows, forward slashes in args are fine.

Restart Claude Desktop completely (quit fully, then reopen). The Parzley tools will appear as a 🔧 hammer icon in the chat input bar.

---

Connecting to Claude.ai (remote)

Streamable HTTP (recommended; works through Cloudflare) — endpoint /mcp:

python main.py --transport http --port 8001

Then in Claude.ai → Settings → Integrations → Add MCP Server:

• URL: https://your-domain.com:8001/mcp

SSE (legacy; some setups need Cloudflare proxy adjustments) — endpoint /sse:

python main.py --transport sse --port 8001

• URL: https://your-domain.com:8001/sse

---

Railway (or any PaaS)

Deploy is not configured in-repo — set this in your host’s UI (example for Railway):

1. Builder: Nixpacks (or Railpack), not Dockerfile unless you add your own Dockerfile.
2. Install: Let Nixpacks auto-detect pyproject.toml, or use a custom install step such as python -m pip install . from the repo root.
3. Start command: python main.py --transport http --host 0.0.0.0
4. Port: The platform sets PORT (e.g. 8080). main.py reads PORT from the environment so you do not need --port in the start command.

MCP URL: https://<your-app>/mcp (HTTPS on the host; no port in the URL for a default HTTPS setup).

If deploy still says “Build image” or Docker, switch the service off Dockerfile builder in settings — this repo does not ship a Dockerfile.

---

Available tools (9 total)

Tool	Description
get_form_with_shortcode	Resolve a shortcode and start a new form-filling session. Must be called first.
parzley_message_turn	Single MCP call that runs concierge_chat and chat_with_agents in parallel — use on every user message after get_form_with_shortcode.
register_respondent	Link name + email to the session. Optional in chat — strongly recommended so the user can open and manage their answers in the Parzley web app (browser access is tied to that email). Call after the first successful parzley_message_turn when the user agrees.
get_schema	Fetch the full form definition (schema, uiSchema, formContext, etc.) for a MongoDB form_object_id (not a shortcode).
get_form_data_by_session	Fetch field values already saved for a session_id.
get_form_data_feedback	Feedback on form data quality, gaps, and validation for the session (errors and shortfalls vs concierge “what to ask next”).
submit_form_data	Final submission (locks the form); use the 6-character session shortcode.
extract_content	Upload a file (PDF or image) to extract raw text / vision description via LlamaParse or VisionAgent (Groq).
analyse_content	Upload a file and analyse its content against a user query to map data to form fields.

---

Session flow

User provides shortcode
        │
        ▼
  get_form_with_shortcode(shortcode)
  ── returns session_id + crew_shortcode
        │
        ▼
  On EVERY user message:
        parzley_message_turn(session_id, …)  ← MCP tool; runs concierge_chat + chat_with_agents in parallel
        │
        ▼
  get_form_data_feedback(session_id)
  ── returns structured document output

Shortcode types

Length	Role	Behaviour
5 chars	Crew / empty template	Identifies the empty form for that crew; get_form_with_shortcode starts work against that template. Sending data via parzley_message_turn creates a 6-character session.
6 chars	Session + saved data	Identifies a specific form instance and answers. Resolved via the API to crew_shortcode and session_id for resume.

---

File upload tools

Both extract_content and analyse_content accept files as base64-encoded strings and send them to Parzley as multipart/form-data with the raw binary.

extract_content — required fields:

Field	Type	Description
file_base64	string	Base64-encoded file contents
file_name	string	Original filename with extension (e.g. resume.pdf)
session_id	string	Session ID from get_form_with_shortcode
form_id	string	Form ID to extract content for

analyse_content — required + optional fields:

Field	Type	Required	Description
file_base64	string	✅	Base64-encoded file contents
file_name	string	✅	Original filename with extension
session_id	string	✅	Session ID from get_form_with_shortcode
user_query	string	✅	Query describing what to extract / analyse
form_id	string	❌	Form ID to analyse content against
extraction_field	string	❌	Specific field to target for extraction

---

Typical Claude conversation

Once connected, try:

"I'd like to fill a form"

Claude will:

1. Ask for your shortcode
2. Call get_form_with_shortcode with the shortcode you provide
3. Store session_id and crew_shortcode for the session
4. Call parzley_message_turn on every message (it runs the concierge + agent APIs in parallel)
5. Guide you through the form question by question
6. Call get_form_data_feedback when you need structured feedback on data quality / gaps

---

Smoke test (optional)

After install:

python -m unittest tests.test_smoke -v

---

Notes

• Timeouts: File upload tools (extract_content, analyse_content) use a 120-second timeout. All other tools use 60 seconds.
• Parallel calls: The parzley_message_turn tool invokes both HTTP endpoints together; do not call them separately from MCP.

---

Troubleshooting

Problem	Fix
Tools don't appear in Claude	Check the config file path, quit and fully reopen Claude Desktop
ModuleNotFoundError	Run pip install . from the project root (Python 3.13+)
Server crashes on start	Run python main.py in a terminal to see the error
502 on Railway / reverse proxy	Confirm main.py is running, PORT matches the platform, and the start command is correct (see Railway above).
File upload fails	Ensure the file is properly base64-encoded and file_name has the correct extension
Client says get_form_with_shortcode is missing but lists other Parzley tools	The server registers all 9 tools (see parzley_mcp/tools/). The client may be filtering or searching a subset — open the full MCP tool list, reconnect the server, or turn off tool search for the first step. get_form_with_shortcode must run first with the user’s shortcode.