Instafill.ai MCP Server Documentation

MCP server URL
https://api.instafill.ai/mcp

Works with Claude Desktop, Claude.ai, Claude Code CLI, ChatGPT, and Codex (CLI, IDE extension, desktop app). Setup steps are in Installation.

Overview

The Instafill.ai MCP (Model Context Protocol) Server connects AI assistants to the Instafill.ai automated PDF form filling service. The connection lets you access, search, and fill PDF forms directly through conversational AI without switching contexts or using multiple tools.

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. The Instafill.ai MCP Server implements this protocol to provide your AI assistant with direct access to your PDF forms and document workflows.

Key Features

  • Document Management: List, search, and retrieve PDF forms from your Instafill.ai workspace
  • Automated Form Filling: Create fill sessions with data from URLs or custom sources
  • Form Structure Editing: Inspect form fields and update their attributes before filling
  • Secure Authentication: OAuth 2.1 with PKCE flow, your credentials stay with Instafill.ai
  • Real-time Status Tracking: Monitor fill session progress and results
  • Document Upload: Upload new PDF forms for processing

Use Cases

  • Automate repetitive form filling tasks through natural language
  • Batch process multiple forms with consistent data
  • Search and retrieve specific forms from large document libraries
  • Fill forms with data from external sources (URLs, web pages, APIs)

Getting Started

Prerequisites

  • Claude Desktop (recommended), Claude.ai with MCP support, Claude Code CLI, ChatGPT with Developer mode, or Codex (CLI, IDE extension, or desktop app)

That's it! If you don't have an Instafill.ai account, you can create one during the authentication process.

Installation

Option 1: Claude Desktop (Recommended)

1. Open Claude Desktop Settings

Launch Claude Desktop and navigate to Settings > Connectors.

2. Add Custom Connector

Click the "Add Custom Connector" button.

3. Enter Connector Name

In the "Name" field, enter a name for the connector, for example Instafill.ai. The "Add" button stays disabled until a name is entered.

4. Configure MCP Server URL

In the "Remote MCP server URL" field, enter:

https://api.instafill.ai/mcp

5. Connect and Authenticate

After adding the connector, click the "Connect" button to authenticate:

  • New users: Sign up for Instafill.ai during the OAuth flow
  • Existing users: Log in with your Instafill.ai credentials

In the browser, select a workspace and approve access on the "Application Access Request" page, see Initial Setup.

Option 2: Claude.ai

MCP server integration via Claude.ai is available for Claude Pro and Team plan users.

1. Open Connectors Settings

Navigate to https://claude.ai/customize/connectors

2. Add Custom Connector

Click the + icon, then click Add custom connector button.

3. Enter Connector Name

In the "Name" field, enter a name for the connector, for example Instafill.ai. The "Add" button stays disabled until a name is entered.

4. Configure MCP Server URL

In the "Remote MCP server URL" field, enter:

https://api.instafill.ai/mcp

5. Save and Authenticate

Click the "Add" button, then click the "Connect" button to authenticate. In the browser, select a workspace and approve access on the "Application Access Request" page, see Initial Setup.

Option 3: Claude Code CLI

Claude Code CLI provides command-line access to Claude with MCP support.

1. Install Claude Code CLI

If you haven't installed Claude Code CLI yet, follow the installation instructions at Claude Code documentation.

2. Add Instafill.ai MCP Server

Run the following command in your terminal:

claude mcp add --transport http instafill https://api.instafill.ai/mcp

3. Launch Claude Code

Start Claude Code in your project directory:

claude

4. Authenticate

Use the /mcp command to view MCP servers and authenticate:

/mcp

Select "Authenticate" when prompted and follow the OAuth flow in your browser: log in, select a workspace, and click "Allow Access".

5. Start Using Instafill.ai Tools

Once authenticated, you can use Instafill.ai tools through natural language:

"Show me all my PDF forms"

Option 4: ChatGPT

MCP server integration via ChatGPT is available for ChatGPT Plus, Team, and Enterprise users with Developer mode enabled.

1. Enable Developer Mode

Navigate to Settings > Apps > Advanced settings and ensure Developer mode is enabled (not available on free ChatGPT plan).

2. Create New App

Click "Create App" button.

3. Configure App Settings

  • Name: Autofill PDF
  • Description: (optional) Fill PDF forms with Instafill.ai
  • MCP Server URL: https://api.instafill.ai/mcp
  • Authentication: OAuth

4. Accept and Create

Check the "I understand and want to continue" checkbox and click "Create".

5. Authenticate

After creating the app, follow the OAuth flow to authenticate with your Instafill.ai account: log in, select a workspace, and click "Allow Access".

Option 5: Codex IDE Extension (VS Code)

The Codex extension for VS Code manages MCP servers from its settings panel.

1. Open MCP Settings

In the Codex panel, open the gear menu and select MCP settings to reach the "MCP servers" screen.

2. Add Server

Click the "+ Add server" button. The "Connect to a custom MCP" dialog opens.

3. Configure the Server

  • Name: instafill
  • Transport: select the "Streamable HTTP" tab
  • URL: https://api.instafill.ai/mcp
  • Leave "Bearer token env var" and headers empty, authentication uses OAuth

Click "Save".

4. Authenticate

On the "MCP servers" screen, click the "Authenticate" button next to the server and follow the OAuth flow in your browser: log in, select a workspace, and click "Allow Access".

5. Reload If Needed

If Instafill.ai tools don't appear after authentication, click "Restart extension" on the "MCP servers" screen.

Option 6: Codex CLI

Codex CLI manages MCP servers with the codex mcp command family.

1. Add Instafill.ai MCP Server

Run the following command in your terminal:

codex mcp add instafill --url https://api.instafill.ai/mcp

2. Authenticate

Start the OAuth flow:

codex mcp login instafill

Your browser opens the Instafill.ai authentication page: log in, select a workspace, and click "Allow Access".

3. Verify the Connection

codex mcp list

4. Start Using Instafill.ai Tools

Launch codex and use the tools through natural language:

"Show me all my PDF forms"

Option 7: Codex App (macOS/Windows)

The Codex desktop app reads the same ~/.codex/config.toml as Codex CLI, so the server is configured once for both.

1. Add Instafill.ai MCP Server

Add the server with Codex CLI as in Option 6, or add this block to ~/.codex/config.toml manually:

[mcp_servers.instafill]
url = "https://api.instafill.ai/mcp"

2. Authenticate

Run codex mcp login instafill in your terminal and complete the OAuth flow in the browser. Codex stores the credentials for all Codex surfaces.

3. Restart the App

Restart the Codex app so it picks up the new server, then use Instafill.ai tools through natural language.

Initial Setup

When you connect, the OAuth flow opens in your browser and prompts you to:

  1. Login or Sign Up: Connect or create your Instafill.ai account
  2. Select Workspace: On the "Application Access Request" page, choose the workspace the AI assistant should access in the "Select Workspace" dropdown. Tools will only see forms and profiles from this workspace
  3. Grant Permissions: Review the requested permissions and click "Allow Access"

Once setup is complete, you can start using Instafill.ai tools through natural language commands.

Authentication

OAuth 2.1 Flow

The Instafill.ai MCP Server uses OAuth 2.1 with PKCE (Proof Key for Code Exchange) for secure authentication. This ensures that your credentials are never shared with the AI assistant or stored on third-party servers.

Authentication Process

  1. Initial Request: When you use an Instafill.ai tool, the MCP server checks for valid authentication
  2. OAuth Redirect: If not authenticated, you're redirected to Instafill.ai authentication page
  3. Login or Sign Up: Sign in with existing credentials or create a new account
  4. Workspace Selection: On the "Application Access Request" page, choose which workspace the AI assistant should access
  5. Authorization: Review the requested permissions and click "Allow Access"

Security Features

  • Workspace Isolation: Access is scoped to your selected workspace
  • No Credential Storage: Your password is never stored by the MCP server
  • Revocable Access: You can revoke MCP access anytime from your Instafill.ai account settings

Token Management

  • Access Tokens: Valid for the duration of your session
  • Automatic Refresh: Tokens are automatically refreshed when needed
  • Secure Storage: Tokens are stored securely by your AI client

Available Tools

The Instafill.ai MCP Server provides 20 tools for managing forms, profiles, and form filling. All tools operate within your currently selected workspace.

Client-Specific Tool Filtering

The MCP server automatically detects your client type and shows only relevant tools:

  • Claude Desktop, Claude.ai, Claude Code CLI: All tools are available except fill_form_widget (you'll use fill_form instead)
  • Codex (CLI, IDE extension, desktop app): All tools are available except fill_form_widget (you'll use fill_form instead)
  • ChatGPT: All tools are available except fill_form (you'll use fill_form_widget instead)

This filtering happens automatically during connection - no configuration needed. You'll only see tools that work with your AI assistant.

List Forms

Tool Name: list_forms

Description: Retrieves a list of all unfilled form templates in your workspace (empty forms that can be filled).

Parameters: None

Returns:

  • List of unfilled form templates with metadata (name, ID, upload date)
  • Total count of form templates
  • Conversion status for each form template

Example Usage:

User: "Show me all my form templates"
AI: [Calls list_forms and displays formatted list]

Use Cases:

  • Browse available form templates
  • Get form IDs for filling operations
  • See which form templates are available for filling

List Filled Forms

Tool Name: list_filled_forms

Description: Retrieves a list of all filled form sessions (completed fill jobs) in your workspace.

Parameters: None

Returns:

  • List of filled forms with metadata (session ID, form name, status, timestamps)
  • Web UI links to view filled forms online
  • Total count of filled forms
  • Completion status for each fill job

Example Usage:

User: "Show me all my filled forms"
AI: [Calls list_filled_forms and displays formatted list]

User: "List completed form fill jobs from last month"
AI: [Calls list_filled_forms and filters by date]

Use Cases:

  • Browse completed form fill jobs
  • Get session IDs for downloading filled forms
  • Track form filling history
  • Find specific filled forms by name or date
  • Verify which forms have been completed

Response Fields:

  • session_id: Unique identifier for the fill job (use with download_filled_form or get_filled_form_data)
  • form_id: ID of the original form template
  • form_name: Name of the filled form
  • status: Fill job status (e.g., "completed", "processing", "failed")
  • filled_form_url: Web UI link to view the filled form online
  • created: When the fill job was created
  • modified: When the fill job was last updated

List Profiles

Tool Name: list_profiles

Description: Retrieves a list of all profiles (structured data sources) in your workspace. Profiles are reusable collections of files and text information that can be used to fill multiple forms.

Parameters:

  • name (optional): Filter profiles by name (partial match)
  • page (optional): Page number for pagination (starts at 1, default: 1)
  • size (optional): Number of results per page (1-100, default: 20)

Returns:

  • List of profiles with metadata (name, files, text data, timestamps)
  • Pagination metadata (total count, current page)
  • Status for each profile

Example Usage:

User: "List my profiles"
AI: [Calls list_profiles and displays formatted list]

User: "Show me profiles with name John"
AI: [Calls list_profiles with name="John" filter]

Use Cases:

  • Browse available profile data sources
  • Find specific profiles by name
  • Get profile IDs for form filling operations
  • View all saved profile data

Get Form Details

Tool Name: get_form_details

Description: Retrieves detailed information about a specific form, including the number of fillable fields.

Parameters:

  • form_id (required): The unique identifier of the form

Returns:

  • Form metadata (name, upload date, page count)
  • Number of fillable fields
  • Form status

Example Usage:

User: "Show me details about the W-9 form"
AI: [Calls get_form_details with form_id and displays information]

Use Cases:

  • Check if a form is ready for filling
  • Verify number of fields in a form
  • Get basic form information

Get Form Fields

Tool Name: get_form_fields

Description: Retrieves the fields of a converted form, grouped by their logical group. Each field carries its id, name, description, control type, the control types it can be changed to (allowed types), max length, page number, section, example values, ids of fields it depends on, and an ignore flag marking fields excluded from form filling. Max length is the character cap a field can hold, so a small value silently truncates longer fill values.

Parameters:

  • form_id (required): The unique identifier of the form

Returns:

  • Field groups, each containing its fields
  • For every field: id, name, description, control type, the control types it can be changed to (allowed types), max length, page number, section, example values, dependency field ids, and ignore flag

Example Usage:

User: "Show me the structure of the W-9 form"
AI: [Calls get_form_fields and displays fields grouped by section]

User: "Which fields are excluded from form filling?"
AI: [Calls get_form_fields and lists fields with ignore=true]

Use Cases:

  • Inspect a form's structure before filling it
  • Obtain field ids before calling update_form_fields
  • Review which fields are active for form filling

Update Form Fields

Tool Name: update_form_fields

Description: Updates attributes of form fields by field id: name, description, group, section, control type, max length, example values, and active status. Only provided attributes change, omitted ones stay as they are. Control type changes only between text-like types (Text, Number, Date, Time) along allowed transitions; checkbox, radio, combobox, and textarea types are fixed. The examples array replaces the field's whole list, an empty array clears it. Setting ignore to true excludes the field from form filling, false reactivates it. Changes propagate to related fill sessions.

Parameters:

  • form_id (required): The unique identifier of the form
  • fields (required): Array of field updates, one entry per field id with only the attributes to change

Returns:

  • Count of updated form templates
  • Count of synced fill sessions

Example Usage:

User: "Rename the 'Address' field to 'Home address' and add an example value"
AI: [Calls get_form_fields to find the field id, then update_form_fields]

User: "Exclude the signature field from form filling"
AI: [Calls update_form_fields with ignore=true for that field]

Use Cases:

  • Improve field names and descriptions for better form filling accuracy
  • Add example values that guide how a field gets filled
  • Exclude irrelevant fields from form filling

Important Notes:

  • Requires a paid subscription
  • Use get_form_fields first to obtain field ids
  • Each field id may appear only once per request
  • Control type changes only between text-like types (Text, Number, Date, Time) along allowed transitions; checkbox, radio, combobox, and textarea types are fixed (see each field's allowed types in get_form_fields)

Update Field Dependencies

Tool Name: update_field_dependencies

Description: Sets, per field, which other fields it depends on (its depends_on list). A field that depends on others is filled after them, with their filled values added to its context, for example to fill a field only when a related field has a certain value. Each entry replaces one field's whole dependency list, an empty depends_on clears it, and fields you do not list keep their current dependencies. Every referenced field id must exist in the form, a field cannot depend on itself, and the dependencies cannot form a cycle.

Parameters:

  • form_id (required): The unique identifier of the form
  • dependencies (required): Array of per-field updates, each with a field_id and the complete depends_on list of field ids it depends on

Returns:

  • The form's full dependency set after the changes are applied

Example Usage:

User: "Only fill the spouse details when marital status is married"
AI: [Calls get_form_fields to find the field ids, then update_field_dependencies so the spouse fields depend on the marital status field]

User: "Remove the dependency on the 'Other' checkbox for this field"
AI: [Calls update_field_dependencies with an empty depends_on for that field]

Use Cases:

  • Make conditional fields fill only when a related field has a certain value
  • Link fields so the assistant fills them in the right order with shared context
  • Clear or adjust dependencies that were set automatically during conversion

Important Notes:

  • Requires a paid subscription
  • Use get_form_fields first to obtain field ids and review current dependencies
  • Each field id may appear only once per request
  • The dependencies cannot form a cycle, and a field cannot depend on itself

Get Profile Details

Tool Name: get_profile_details

Description: Retrieves detailed information for a single profile by profile_id, including name, files, text data, and timestamps.

Parameters:

  • profile_id (required): The unique identifier of the profile to retrieve

Returns:

  • Profile name and status
  • List of associated files with metadata (name, size, upload date)
  • Text information with encryption status
  • Creation and modification timestamps

Example Usage:

User: "Show details for profile ID abc-123"
AI: [Calls get_profile_details with profile_id and displays information]

User: "What files are in profile xyz-456?"
AI: [Gets profile details and lists files]

Use Cases:

  • View specific profile information before using it for form filling
  • Check what data is stored in a profile
  • Verify profile files and text content
  • Review profile metadata and status

Create Profile

Tool Name: create_profile

Description: Creates a new empty profile in the user's workspace with default name "New profile" and "Draft" status.

Parameters: None

Returns:

  • profile_id: The unique identifier of the new profile
  • name: Default name ("New profile")
  • status: Initial status ("Draft")

Example Usage:

User: "Create a new profile"
AI: [Calls create_profile and returns the new profile_id]

User: "I need a new profile for my tax documents"
AI: [Creates profile, then updates name and uploads files]

Use Cases:

  • Start building a new profile for form filling
  • Create a profile before adding text info or files
  • Set up reusable data sources for multiple forms

Update Profile Text Info

Tool Name: update_profile_text_info

Description: Updates the text data for an existing profile. Replaces previous text content with the new data. The profile name may be auto-generated if it is still the default "New profile".

Parameters:

  • profile_id (required): The unique identifier of the profile to update
  • text_info (required): The text data to set on the profile

Returns:

  • profile_name: The updated profile name (may be auto-generated)

Example Usage:

User: "Update profile abc-123 with my resume data: John Doe, Software Engineer..."
AI: [Calls update_profile_text_info with profile_id and text_info]

User: "Add my personal info to profile xyz-456"
AI: [Calls update_profile_text_info with the provided data]

Use Cases:

  • Add personal information to a profile for form filling
  • Update existing profile data with new information
  • Populate a newly created profile with text content

Update Profile Name

Tool Name: update_profile_name

Description: Updates the name of an existing profile. Names longer than 200 characters are automatically truncated.

Parameters:

  • profile_id (required): The unique identifier of the profile to rename
  • name (required): The new name for the profile (max 200 characters)

Returns:

  • success: Boolean indicating whether the update was applied

Example Usage:

User: "Rename profile abc-123 to 'John Doe Resume'"
AI: [Calls update_profile_name with profile_id and new name]

Use Cases:

  • Give a meaningful name to a newly created profile
  • Rename existing profiles for better organization

Upload Profile Files

Tool Name: upload_profile_files

Description: Generates a secure upload link for adding files to an existing profile. Supported formats: PDF, DOCX, DOC, TXT. Duplicate files are detected and skipped automatically.

Parameters:

  • profile_id (required): The unique identifier of the profile to upload files to

Returns:

  • upload_url: Temporary URL for uploading files (valid for 10 minutes)
  • profile_id: The profile ID for reference

Example Usage:

User: "Upload files to profile abc-123"
AI: [Calls upload_profile_files and provides upload link]

User: "Add my resume PDF to profile xyz-456"
AI: [Generates upload URL for the user to upload the file]

Use Cases:

  • Add PDF, DOCX, DOC, or TXT files to a profile
  • Upload supporting documents for form filling
  • Build comprehensive profiles with multiple file sources

Upload Process:

  1. Get upload URL from this tool
  2. Open the URL in a browser
  3. Select and upload files (multiple files supported)
  4. Return to chat when upload is complete

Important Notes:

  • Upload URL is valid for 10 minutes only
  • Each upload URL can only be used once
  • Maximum file size: 10 MB per file
  • Duplicate files are automatically detected and skipped

Search Forms

Tool Name: search_forms

Description: Search for forms by name using full-text search.

Parameters:

  • query (required): Search query string (searches form names only)
  • limit (optional): Maximum number of results (1-100, default: 20)
  • offset (optional): Number of results to skip for pagination (default: 0)

Returns:

  • List of matching forms in relevance order
  • Form metadata

Example Usage:

User: "Find all tax forms"
AI: [Calls search_forms with query="tax" and displays results]

Use Cases:

  • Find specific forms by name
  • Filter large form libraries
  • Quickly locate forms without browsing full list

Fill Form

Tool Name: fill_form

Availability: Claude Desktop, Claude.ai, and Claude Code CLI. Not available in ChatGPT (use fill_form_widget instead).

Description: Fill a form with provided data from various sources.

Parameters:

  • form_id (required): The form to fill
  • At least one data source (required):
    • file_urls: URLs to documents/web pages with data
    • profile_ids: Saved profile IDs
    • text_info: Any text data

Returns:

  • Session ID for tracking the fill job
  • Initial status

Example Usage:

User: "Fill the W-9 form with data from my website profile"
AI: [Calls fill_form with form_id and file_urls]

Use Cases:

  • Fill forms with data from web pages
  • Fill forms with saved profiles
  • Fill forms with manually provided text data
  • Batch process multiple forms

Fill Form Widget (ChatGPT Only)

Tool Name: fill_form_widget

Availability: ChatGPT only (requires Developer mode enabled). Automatically hidden from Claude Desktop, Claude.ai, and Claude Code CLI.

Description: Opens a secure widget for filling a form. The widget supports two modes: entering text data or selecting a saved profile. The user provides their data directly in the widget (not in chat context). Returns a session_id to track the fill job.

Parameters:

  • form_id (required): The unique identifier of the form to fill

Returns:

  • Widget interface for secure data entry with two modes:
    • Text Data: Text input for entering personal information directly
    • Profile: Dropdown to select a saved profile as the data source for form filling
  • Session ID for tracking the fill job (after submission)

Example Usage:

User: "I want to fill the W-9 form with my personal information through the widget"
ChatGPT: [Opens fill_form_widget and displays secure input form]

User: [Enters data in widget or selects a profile, then submits]
ChatGPT: "Form filling started! Session ID: abc-123. Use check_form_fill_status to monitor progress."

Use Cases:

  • Fill forms using a dedicated data entry interface
  • Fill forms using a previously saved profile
  • Enter data directly in a widget instead of chat
  • Keep form data separate from conversation history

Important Notes:

  • Only available in ChatGPT with Developer mode enabled (automatically hidden from Claude clients)
  • Data entered in the widget is not stored in chat context
  • Widget session expires after 10 minutes if not submitted
  • Saved profiles are fetched automatically when the widget opens, if no profiles exist, the Profile mode is disabled
  • Use check_form_fill_status to monitor the fill job after submission

Check Form Fill Status

Tool Name: check_form_fill_status

Description: Check the status of a form fill job and retrieve results when complete.

Parameters:

  • session_id (required): Session ID from fill_form or fill_form_widget

Returns:

  • Current status (queued, processing, completed, failed)
  • Filled form (when completed)
  • Error details (if failed)

Example Usage:

User: "Is my form ready?"
AI: [Calls check_form_fill_status and reports progress]

Use Cases:

  • Monitor form fill progress
  • Retrieve completed forms
  • Check for errors during filling

Get Filled Form Data

Tool Name: get_filled_form_data

Description: Retrieves structured field data from a completed form fill job as JSON. Returns all form fields with their filled values, including field names, descriptions, groups, page numbers, and the actual filled values.

Parameters:

  • session_id (required): The unique identifier of the completed fill job

Returns:

  • Fill job metadata (session_id, form_id, formName)
  • Array of fields with filled data:
    • name: Field name
    • description: Field description
    • group: Field group/category
    • page_num: Page number
    • value: Filled value (the key data)
  • Timestamps (created, modified)

Example Usage:

User: "Get the filled data from my W-9 form"
AI: [Calls get_filled_form_data and displays structured JSON with all field values]

User: "Extract the data from form A and use it to fill form B"
AI: [Gets data from job A, then fills form B using extracted values]

Use Cases:

  • Extract structured data from filled forms for further processing
  • Reuse filled data to populate another form
  • Verify fill results field-by-field
  • Export form data to other systems (JSON format)
  • Create data pipelines: Form A -> Extract Data -> Form B

Requirements:

  • Fill job must have status = "completed"
  • Returns error if job is not completed yet

Get Fill Inputs

Tool Name: get_fill_inputs

Description: Retrieves the input sources of a fill session: uploaded files with URLs reusable in fill_form, decrypted text input, and profile ids. Works for sessions in any status. Profile data is not repeated in files or text, pass the returned profile ids to fill_form instead.

Parameters:

  • session_id (required): The unique identifier of the fill session

Returns:

  • files: Uploaded files with URLs reusable as file_urls in fill_form
  • text_info: Decrypted text input (truncated past 10000 characters)
  • profile_ids: Profiles used as data sources

Example Usage:

User: "My fill job failed, retry it with the same data"
AI: [Calls get_fill_inputs, then fill_form with the returned sources]

User: "What data was used to fill this form?"
AI: [Calls get_fill_inputs and lists files, text, and profiles]

Use Cases:

  • Resubmit the same data after a failed fill
  • Reuse one session's inputs to fill another form
  • Review which sources produced a fill

Download Filled Form

Tool Name: download_filled_form

Description: Downloads the filled PDF form after a successful form fill job. Returns a download URL for the filled PDF file that the user can open in their browser.

Parameters:

  • session_id (required): The session ID from a completed fill_form or fill_form_widget job

Returns:

  • download_url: URL to download the filled PDF
  • filename: Name of the filled PDF file
  • session_id: The session ID
  • message: Instructions and validity information

Example Usage:

User: "Download the filled form from session abc-123"
AI: [Calls download_filled_form with session_id and provides download link]

User: "Get the PDF file for completed job xyz-789"
AI: [Verifies completion status and returns download URL]

Use Cases:

  • Download filled PDF forms to local device
  • Save completed forms for record keeping
  • Share filled forms with others
  • Archive completed form fill jobs

Important Notes:

  • Form fill status must be "completed" - use check_form_fill_status first if unsure
  • Download URL is valid for 10 minutes only
  • Each download URL can only be used once for security
  • Opens in browser for immediate download

Upload Form

Tool Name: upload_form

Description: Generate a secure upload URL for adding new forms to your workspace.

Parameters: None

Returns:

  • Temporary upload URL (valid for 10 minutes)
  • Upload instructions

Example Usage:

User: "I want to upload a new form"
AI: [Calls upload_form and provides upload link]

Use Cases:

  • Add new forms to your workspace
  • Import forms from other sources
  • Build form libraries

Upload Process:

  1. Get upload URL from this tool
  2. Upload form file to the provided URL
  3. File is automatically processed and added to workspace

Workspace Management

Understanding Workspaces

Workspaces in Instafill.ai allow teams to organize and share PDF forms within an organization. Each workspace has:

  • Isolated Form Library: Forms in one workspace are not visible in others
  • Member Access Control: Users can be added or removed from workspaces
  • Separate Settings: Each workspace has its own configuration

Troubleshooting

Common Issues

1. Authentication Failures

Error: "Authentication required. Please log in to use this tool."

Causes:

  • Session expired
  • Invalid OAuth token
  • Revoked access

Solutions:

  1. Restart Claude Desktop to trigger new OAuth flow
  2. For Codex, re-authenticate with codex mcp login instafill
  3. Check your Instafill.ai account is active
  4. Verify workspace membership
  5. Clear Claude Desktop cache and reconnect

2. Workspace Access Denied

Error: "System user does not have access to this workspace" or "Cannot access workspace"

Causes:

  • You're not a member of the target workspace
  • Workspace permissions changed

Solutions:

  1. Verify workspace membership in Instafill.ai web UI
  2. Ask workspace admin to add you as a member
  3. Re-authenticate to refresh permissions
  4. Contact support if issue persists

3. Form Not Found

Error: "Form not found" or 404 errors

Causes:

  • Form deleted from workspace
  • Wrong workspace context
  • Incorrect form ID

Solutions:

  1. Use list_forms() to verify form exists
  2. Check you're in the correct workspace
  3. Verify form ID is correct
  4. Form may have been moved to another workspace

4. Form Fill Timeout

Error: "Fill job timed out" or no results after long wait

Causes:

  • Source URLs not accessible
  • Network connectivity issues
  • Complex form taking too long to process

Solutions:

  1. Verify source URLs are publicly accessible
  2. Check URL data is properly formatted
  3. Retry after a few minutes
  4. Contact support for complex cases

5. Slow Response Times

Symptoms: Tools taking longer than expected to respond

Causes:

  • Complex search queries
  • Network latency

Solutions:

  1. Use more specific search queries
  2. Filter results with limit parameter
  3. Wait a moment and retry

6. Upload URL Expired

Error: "Upload token expired" when uploading file

Cause: Upload URLs are valid for 10 minutes only

Solutions:

  1. Request new upload URL with upload_form()
  2. Upload file immediately after receiving URL
  3. Don't reuse old upload URLs

7. Form Not Fillable

Error: Form shows as not converted or not ready

Cause: The form is a flat (non-fillable) form that hasn't been converted yet

Solutions:

  1. Use get_form_details() to check form status
  2. Wait for conversion to complete
  3. Contact support if conversion fails

8. Using the Form Fill Widget in ChatGPT

Scenario: When filling forms with personal information in ChatGPT

Solution:

ChatGPT users automatically have access to the fill_form_widget tool instead of fill_form. This widget provides a dedicated data entry interface outside the chat context:

User: "I want to fill the W-9 form with my personal information"

ChatGPT: [Opens fill_form_widget with data entry form]

Why the Widget Approach:

  • Provides a dedicated form interface for structured data entry
  • Your data is entered separately from the conversation
  • Data is securely transmitted directly to Instafill.ai servers
  • Widget session expires after 10 minutes for security

Note for Claude and Codex Users:

  • Claude Desktop, Claude.ai, Claude Code CLI, and Codex users have the regular fill_form tool
  • The MCP server automatically shows the correct tool based on your client