Instafill.ai MCP Server Documentation

Overview

The Instafill.ai MCP (Model Context Protocol) Server enables seamless integration between AI assistants and Instafill.ai automated PDF form filling service. This integration allows you to 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 autofill sessions with data from URLs or custom sources
• Secure Authentication: OAuth 2.1 with PKCE flow for enterprise-grade security
• Real-time Status Tracking: Monitor autofill 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, or Claude Code CLI

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. Configure MCP Server URL

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

https://mcp.instafill.ai/mcp

4. 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

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

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

4. Save and Authenticate

Save the connector and click the "Connect" button to authenticate.

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://mcp.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.

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://mcp.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.

Initial Setup

After authentication, you'll be prompted to:

1. Login or Sign Up: Connect or create your Instafill.ai account
2. Select Workspace: Choose the workspace you want to work with
3. Grant Permissions: Authorize the AI assistant to access your forms and documents

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: Choose which workspace the AI assistant should access
5. Authorization: Grant the AI assistant permission to access your forms

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 16 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)
• 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 autofill jobs) in your workspace.

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

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

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

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 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

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.

Returns:

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

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)

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

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

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 (default: 20)

Returns:

• List of matching forms
• Form metadata

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

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)

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

• 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)

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)

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

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

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

• 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.

Returns:

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

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

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. Check your Instafill.ai account is active
3. Verify workspace membership
4. 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 Users:

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