Instafill.ai MCP Server Documentation

Overview

The Instafill.ai MCP (Model Context Protocol) Server enables seamless integration between Claude 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 like Claude to securely connect to external data sources and tools. The Instafill.ai MCP Server implements this protocol to provide Claude 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.0 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/settings/connectors

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.0 Flow

The Instafill.ai MCP Server uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authentication. This ensures that your credentials are never shared with Claude 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 Claude should access
5. Authorization: Grant Claude 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 Claude session
• Automatic Refresh: Tokens are automatically refreshed when needed
• Secure Storage: Tokens are stored securely by Claude Desktop

---

Available Tools

The Instafill.ai MCP Server provides 12 tools for managing and filling forms. 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.

1. 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"
Claude: [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

2. 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"
Claude: [Calls list_filled_forms and displays formatted list]

User: "List completed form fill jobs from last month"
Claude: [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

3. 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"
Claude: [Calls list_profiles and displays formatted list]

User: "Show me profiles with name John"
Claude: [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

4. 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"
Claude: [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

5. 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"
Claude: [Calls get_profile_details with profile_id and displays information]

User: "What files are in profile xyz-456?"
Claude: [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

6. 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"
Claude: [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

7. 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"
Claude: [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

8. 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 with sensitive data. The user provides their data directly in the widget (not in chat context). Returns a session_id to track the fill job. This tool is specifically designed to bypass ChatGPT's safety filters when filling forms with sensitive personal information.

Parameters:

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

Returns:

• Widget interface for secure data entry
• 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 and submits]
ChatGPT: "Form filling started! Session ID: abc-123. Use check_form_fill_status to monitor progress."

Use Cases:

• Fill forms with sensitive personal data (SSN, passport numbers, etc.)
• Bypass ChatGPT safety filters for form filling
• Enter data that shouldn't appear in chat history
• Secure data entry for privacy-sensitive forms

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
• Use check_form_fill_status to monitor the fill job after submission

9. 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?"
Claude: [Calls check_form_fill_status and reports progress]

Use Cases:

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

10. 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"
Claude: [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"
Claude: [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

11. 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"
Claude: [Calls download_filled_form with session_id and provides download link]

User: "Get the PDF file for completed job xyz-789"
Claude: [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

12. 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"
Claude: [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. 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. Filling Forms with Sensitive Data in ChatGPT

Scenario: When filling forms with sensitive personal information (SSN, passport numbers, etc.) in ChatGPT

Solution:

ChatGPT users automatically have access to the fill_form_widget tool instead of fill_form. This widget allows secure data entry outside the chat context:

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

ChatGPT: [Opens fill_form_widget with secure input form]

Why the Widget Approach:

• Bypasses ChatGPT's safety filters for sensitive data processing
• Your data never appears in the conversation history
• 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
• Claude doesn't have the same safety restrictions, so no widget is needed
• The MCP server automatically shows the correct tool based on your client