PARSERGet Started
API ReferenceMCP Server

PARSER GUIDES

MCP Server

Connect AI agents to PARSER using the remote MCP server

PARSER provides a remote Model Context Protocol (MCP) server so AI agents can work with your parsers, document classifiers, documents, folders, fields, reviews, exports, and webhooks using natural language.

Use MCP when you want an AI assistant to help with actions like:

  • Find parsers and inspect parser settings
  • Find document classifiers and inspect routing settings
  • Upload or process documents through a parser or classifier
  • Search documents by name, status, folder, external ID, or extracted values
  • Read and update extracted data
  • Manage folders and move documents
  • Configure fields and table fields
  • Configure automatic document names from extracted field values
  • Configure review stages and approve or reject documents
  • Export selected data as JSON, XML, CSV, or XLSX
  • Manage webhook endpoint settings

The MCP server is built on the same PARSER permissions and public API behavior. It is meant for AI-agent workflows, while the REST API remains the best option for backend-to-backend integrations.

MCP server URL

Add this remote MCP server URL in your MCP client:

https://mcp.PARSER.com/mcp

Authentication

PARSER MCP uses OAuth. Do not create or paste an API key into your MCP client.

When you connect:

1. Your MCP client opens PARSER authentication.

2. Log in to PARSER if needed.

3. Choose the team the AI agent should access.

4. Review the requested access.

5. Approve access.

The connection is scoped to the selected team. MCP tools do not accept a teamId; PARSER uses the team chosen during OAuth consent.

MCP must be included for the selected team. PARSER checks eligibility during connection and again whenever the client uses MCP. If the team no longer qualifies, the saved connection remains visible as Plan required, but the client cannot access team data until eligibility returns.

Setup

Open your MCP client settings

Use a client that supports remote MCP servers with OAuth. The setup usually lives under an area named MCP, Connectors, Tools, or Integrations.

Add the PARSER server

Create a new remote MCP connection with:

Name: PARSER
URL: https://mcp.PARSER.com/mcp

Authenticate

Click Connect, Authenticate, or the equivalent action in your MCP client. PARSER will ask you to log in, choose a team, and approve access.

Test the connection

Ask your AI assistant:

List my PARSER parsers.

If the connection is working, the assistant should call the list_parsers tool and return parsers from the team you selected during OAuth.

Client compatibility

PARSER uses remote Streamable HTTP with JSON responses and OAuth. It supports MCP protocol versions:

  • 2025-11-25 (preferred)
  • 2025-06-18 (compatibility)

Use a current MCP client that supports remote OAuth servers. PARSER is stateless and does not use server-sent event (SSE) sessions.

Available tools

Parsers

  • list_parsers - List available parsers for the connected team.
  • get_parser - Get parser details and settings.
  • create_parser - Create a new parser.
  • update_parser - Update safe parser settings.
  • duplicate_parser - Duplicate parser setup without documents or secrets.
  • configure_parser_fields - Read or replace parser fields and table fields.
  • get_document_naming - Get automatic naming settings and the exact variables available to filename templates.
  • configure_document_naming - Enable, disable, or replace automatic naming rules.

Document classifiers

  • list_classifiers - List available document classifiers for the connected team.
  • get_classifier - Get classifier details and routing settings.
  • create_classifier - Create a classifier with routing rules.
  • update_classifier - Update classifier settings and routing rules.
  • delete_classifier - Delete a classifier. Requires confirm: true.
  • list_classifier_documents - List classifier documents by routing status, search, date, or page.
  • get_classifier_document - Get one classifier document and its latest routing result.
  • reprocess_classifier_document - Re-run classification and routing for a skipped or failed classifier document.

Documents

  • upload_document_url - Process one or more documents from downloadable URLs through a parser or classifier.
  • prepare_document_upload - Create short-lived direct upload URLs for attached or local files.
  • complete_document_upload - Verify a prepared upload and queue the complete batch for processing.
  • upload_document_file - Upload small files as complete base64 content when direct upload is unavailable.
  • search_documents - Search documents by metadata and extracted data.
  • get_document - Get document status, metadata, extracted data, and review summary.
  • get_document_data - Get the latest extracted data for a document.
  • update_document - Update document name, external ID, custom data, assignee, or folder.
  • update_document_data - Patch extracted field and table values.
  • reprocess_document - Re-run extraction for a document.
  • delete_document - Delete one or more documents. Requires confirm: true.

Folders

  • list_folders - List folders in a parser.
  • create_folder - Create a folder.
  • update_folder - Update a folder.
  • delete_folder - Delete a folder. Requires confirm: true.
  • move_documents_to_folder - Move documents into a folder or remove them from folders.

Reviews & Approvals

  • list_reviewers - List eligible reviewers for a parser.
  • list_review_stages - List review stages for a parser.
  • configure_review_stages - Read or replace review stages.
  • approve_document - Approve the current review stage.
  • reject_document - Reject the current review stage.
  • reset_document_review - Reset an approved or rejected document back to review.

Exports and webhooks

  • export_documents - Export selected or filtered documents as JSON, XML, CSV, or XLSX.
  • list_webhooks - List parser webhook endpoint settings.
  • create_webhook - Create a webhook endpoint.
  • update_webhook - Update a webhook endpoint.
  • delete_webhook - Delete a webhook endpoint. Requires confirm: true.

Available resources

MCP resources are read-only JSON snapshots that agents can fetch without inventing a tool call.

Concrete resource roots:

  • PARSER://parsers
  • PARSER://classifiers

Parameterized resource templates:

  • PARSER://parsers/{parserId}
  • PARSER://classifiers/{classifierId}
  • PARSER://classifiers/{classifierId}/documents/{documentId}
  • PARSER://parsers/{parserId}/fields
  • PARSER://parsers/{parserId}/folders
  • PARSER://parsers/{parserId}/review-stages
  • PARSER://parsers/{parserId}/document-naming
  • PARSER://parsers/{parserId}/documents/{documentId}

Common workflows

Process a document from a URL

Ask:

Process this invoice in my Invoices parser: https://example.com/invoice.pdf

The agent should:

1. Find the parser, if needed.

2. Call upload_document_url.

3. Return the new document ID and initial processing status.

4. Poll with get_document or get_document_data until processing completes.

Route a mixed batch

Ask:

Upload this file to my Claims intake classifier: https://example.com/mixed-claim.pdf

The agent should:

1. Find the classifier, if needed.

2. Call upload_document_url with the classifier.

3. Return the initial classifier document status.

4. Poll with get_classifier_document until routing finishes.

5. Use parser document tools after the routed document is processed by the target parser.

Inspect and retry classifier routing

Ask:

Show failed or skipped documents in my Claims intake classifier and reprocess the latest failed one.

The agent can use list_classifier_documents, inspect the routing category, destination parser, reasoning, and safe failure details with get_classifier_document, then call reprocess_classifier_document.

Upload a local file

For an attached or local file, prefer direct upload. The file bytes go straight to PARSER storage and do not pass through a base64 MCP argument.

The agent should:

1. Read each filename and byte size from the local file.

2. Call prepare_document_upload with one parser or classifier and up to 20 files. Each file can be up to 100 MB.

3. Upload each file's raw bytes with the returned PUT URL and headers. The signed URLs expire after 15 minutes.

4. After every upload returns a successful HTTP status, call complete_document_upload with the returned document IDs.

5. Poll with get_document, get_document_data, or get_classifier_document until processing completes.

Do not base64-encode files for this workflow. Treat each signed upload URL as a temporary credential and do not share or log it.

If a file is already available through a downloadable public URL, upload_document_url is also suitable. If the MCP client cannot make the signed PUT request, upload_document_file remains a small-file fallback. Its canonical file shape is { filename, contentType, contentBase64 }, and one request is limited to 2 MiB of decoded data in total.

PARSER validates the complete batch metadata before preparing documents and verifies every direct-uploaded object against its expected size before queueing it. Inline PDFs are also checked for truncated or corrupted base64 content before they reach the Document Inbox.

Search and update extracted data

Ask:

Find invoices from Acme in June and update the PO Number on the latest one to PO-1024.

The agent can use search_documents, get_document_data, and update_document_data.

Automatically name invoices after extraction

Ask:

Rename every document in my Invoices parser to Invoice- followed by the extracted Invoice Number.

The agent should:

1. Find the parser with list_parsers.

2. Call get_document_naming to read the current configuration and available variables.

3. Confirm that the parser contains the exact field name Invoice Number.

4. Call configure_document_naming with:

{
  "parserId": "parser-id",
  "enabled": true,
  "defaultTemplate": "Invoice-{{Invoice Number}}"
}

PARSER evaluates the template after extraction and preserves the original file extension. For example, an extracted invoice number of INV-1042 produces Invoice-INV-1042.jpg for an original JPG. Do not add .jpg or another extension to the template.

Template variables are case-sensitive and must exactly match the parser field name, including spaces and punctuation. Conditional naming rules can use extracted fields, document name, created date, folder ID, or folder name. Existing manual document names are not overwritten.

Review a document

Ask:

Show documents waiting for my review, then approve the one from Acme if the total is under 500.

The agent can list reviewers and stages, search documents by review filters, inspect extracted data, and call approve_document with the assigned reviewer ID.

Export data

JSON exports are returned as structured data in the tool result. XML, CSV, and XLSX exports return a temporary download with its filename, content type, size, download URL, and expiry time.

The download URL expires after 15 minutes. Ask the client to save the file before it expires, or run the export again to create a new URL.

File upload reliability

AI clients vary in how they pass local files to MCP tools. For reliable uploads:

  • Provide exactly one destination: parserId or classifierId. A folder can be used only with a parser upload.
  • For attached or local files, use prepare_document_upload, upload the raw bytes to each returned signed URL, then call complete_document_upload.
  • Direct uploads accept up to 20 files and 100 MB per file. The signed upload URLs expire after 15 minutes.
  • upload_document_url accepts up to 20 public HTTP or HTTPS file URLs. Each file can be up to 100 MB.
  • URL downloads can follow up to five safe redirects. Local, private-network, credential-bearing, and non-HTTP URLs are rejected.
  • upload_document_file accepts up to 20 inline files and 2 MiB of decoded file data across the complete request.
  • Do not paste partial base64 or text extracted from a file.
  • For inline base64 PDFs, PARSER checks that the uploaded bytes look like a complete PDF before creating the document.

The whole batch is queued only after every file has been stored. If PARSER storage is interrupted before queueing, PARSER cleans or recovers the partial upload and returns one retriable batch error. Retry the complete batch instead of assuming earlier files were accepted.

Documents process asynchronously. A successful parser upload means the complete batch was accepted and queued; use get_document or get_document_data to check processing status and retrieve extracted data. A successful classifier upload may return routing details first; extracted data is available from the target parser after routing and extraction finish.

Tool results and errors

Successful tools return both readable text and structured PARSER data.

Normal tool failures return isError: true with structured error details:

{
  "code": "validation_error",
  "message": "A safe explanation of what needs to change",
  "retryable": false,
  "requestId": "request-id"
}

Use retryable to decide whether to retry. Keep requestId when contacting support. Authentication failures use HTTP 401; missing scope, permission, or team eligibility uses 403.

Security behavior

  • MCP uses OAuth, not API keys.
  • The MCP access token is scoped to one selected PARSER team.
  • PARSER checks the saved consent, team membership, team eligibility, granted scope, role, and parser or classifier access on every request.
  • Destructive tools require confirm: true.
  • PARSER does not expose billing data, integration credentials, webhook secrets, raw OCR, or deleted records through MCP.
  • Classifiers route documents to parsers. Extracted-data, export, fields, folders, reviews, and webhook tools remain parser tools.
  • Disconnecting an application under Profile settings -> Connections invalidates its existing access on the next request.

Troubleshooting

The browser shows JSON at the MCP URL

If your MCP client opens https://mcp.PARSER.com/mcp in a browser and only shows JSON, the server is returning MCP OAuth discovery metadata. A compatible client should continue the OAuth flow automatically.

If the client stays stuck waiting for a callback, try another MCP client or update the client. The PARSER server supports remote MCP OAuth discovery, but client support can vary.

No parsers are listed

Make sure you chose the correct team during OAuth consent. The MCP connection can only access the team selected during setup.

The team is not available or shows Plan required

MCP must be included for the team. Check the team plan or lifetime license, then reconnect if the team was not available during consent. A saved connection marked Plan required remains blocked until the team becomes eligible again.

Upload succeeded but processing is still running

This is normal. Document processing is asynchronous. Ask the agent to check the document again with get_document or get_document_data.

File upload is rejected as incomplete or corrupted

The MCP client may have sent incomplete base64 file content. Use prepare_document_upload so the client sends the original raw file bytes, or use upload_document_url when the file already has a downloadable URL.

Inline file is too large

Inline base64 uploads are limited to 2 MiB of decoded file data for the complete request. Use prepare_document_upload for an attached or local file, or upload_document_url for an existing downloadable URL.

Direct upload URL expired

Call prepare_document_upload again to create a new signed URL. Do not call complete_document_upload until every replacement upload succeeds.

URL upload is rejected

Confirm that the URL uses HTTP or HTTPS, is publicly reachable without cookies or login credentials, returns the file itself, and does not redirect to a local or private-network address.

Export download expired

XML, CSV, and XLSX download URLs expire after 15 minutes. Run export_documents again to create a fresh URL.

AuthenticationHow to authenticate API requestsOpen guide → WebhooksReceive document.exported events and payload structureOpen guide →