Rossum MCP & Agent

MCP server and AI agent toolkit for intelligent document processing with Rossum.

GitHub

Rossum MCP Server & Rossum Agent

AI-powered Rossum orchestration: Document workflows conversationally, debug pipelines automatically, and configure automation through natural language.

Documentation Python License: MIT

PyPI - rossum-mcp PyPI - rossum-agent PyPI - rossum-agent-client PyPI - rossum-deploy

codecov CodeQL Snyk Security CodeFactor

MCP MCP Tools Rossum API Claude Opus 4.6

Conversational AI toolkit for the Rossum intelligent document processing platform. Transforms complex workflow setup, debugging, and configuration into natural language conversations through a Model Context Protocol (MCP) server and specialized AI agent.

[!NOTE] This is not an official Rossum project. It is a community-developed integration built on top of the Rossum API, not a product (yet).

What Can You Do?

Set up a complete customer organization with queues, schemas, validations, duplicate detection, email notifications, and UI configuration:

1. Create two new queues: Invoices and Credit Notes.
2. Update schemas w.r.t. schema specification (Invoices with 15 fields including line items table, Credit Notes as-is)
3. Add a computed field "The Net Terms" to Invoices queue (Due Date - Issue Date → Net 15/30/Outstanding)
4. Implement duplicate document detection on Document ID
5. Add business validations: total amount cap, line items sum check, quantity × unit price check
6. Add email notification extension on document status change to 'to_review'
7. Update Invoice queue UI settings to display 8 key fields
8. Verify setup by uploading a sample invoice twice (testing duplicate detection)

What This Demonstrates:

  • Queue & Schema Setup: Creates queues with detailed field specifications including line items tables
  • Computed Fields: Adds derived fields with business logic (date difference categorization)
  • Duplicate Detection: Configures document-level deduplication with user-facing messages
  • Business Validations: Implements multi-rule validation (amount caps, sum checks, arithmetic checks)
  • Email Notifications: Sets up templated email alerts triggered by document state changes
  • UI Configuration: Customizes queue column display for operational efficiency
  • End-to-End Verification: Validates the entire setup with real document uploads

This example showcases the agent's ability to set up a production-ready organization from scratch - all from a single conversational prompt.

Automatically analyze and document all hooks/extensions configured on a queue:

Briefly explain the functionality of every hook based on description and/or code one by one for a queue `2042843`.

Store output in extension_explanation.md

What This Does:

  • Lists all hooks/extensions on the specified queue
  • Analyzes each hook's description and code
  • Generates clear, concise explanations of functionality
  • Documents trigger events and settings
  • Saves comprehensive documentation to a markdown file

This example shows how the agent can analyze existing automation to help teams understand their configured workflows.

Set up a complete document splitting and sorting pipeline with training queues, splitter engine, automated hooks, and intelligent routing:

1. Create three new queues in workspace `1777693` - Air Waybills, Certificates of Origin, Invoices.
2. Set up the schema with a single enum field on each queue with a name Document type (`document_type`).
3. Upload documents from folders air_waybill, certificate_of_origin, invoice in `examples/data/splitting_and_sorting/knowledge` to corresponding queues.
4. Annotate all uploaded documents with a correct Document type, and confirm the annotation.
    - Beware document types are air_waybill, invoice and certificate_of_origin (lower-case, underscores).
    - IMPORTANT: After confirming all annotations, double check, that all are confirmed/exported, and fix those that are not.
5. Create three new queues in workspace `1777693` - Air Waybills Test, Certificates of Origin Test, Invoices Test.
6. Set up the schema with a single enum field on each queue with a name Document type (`document_type`).
7. Create a new engine in organization `1`, with type = 'splitter'.
8. Configure engine training queues to be - Air Waybills, Certificates of Origin, Invoices.
    - DO NOT copy knowledge.
    - Update Engine object.
9. Create a new schema that will be the same as the schema from the queue `3885208`.
10. Create a new queue (with splitting UI feature flag!) with the created engine and schema in the same workspace called: Inbox.
11. Create a python function-based the **`Splitting & Sorting`** hook on the new inbox queue with this settings:
    **Functionality**: Automatically splits multi-document uploads into separate annotations and routes them to appropriate queues.
    Split documents should be routed to the following queues: Air Waybills Test, Certificates of Origin Test, Invoices Test

    **Trigger Events**:
    - annotation_content.initialize (suggests split to user)
    - annotation_content.confirm (performs actual split)
    - annotation_content.export (performs actual split)

    **How it works**: Python code

    **Settings**:
    - sorting_queues: Maps document types to target queue IDs for routing
    - max_blank_page_words: Threshold for blank page detection (pages with fewer words are considered blank)
12. Upload 10 documents from `examples/data/splitting_and_sorting/testing` folder to inbox queues.

What This Demonstrates:

  • Queue Orchestration: Creates 7 queues (3 training + 3 test + 1 inbox) with consistent schemas

  • Knowledge Warmup: Uploads and annotates 90 training documents to teach the engine

  • Splitter Engine: Configures an AI engine to detect document boundaries and types

  • Hook Automation: Sets up a sophisticated webhook that automatically:

    • Splits multi-document PDFs into individual annotations
    • Removes blank pages intelligently
    • Routes split documents to correct queues by type
    • Suggests splits on initialization and executes on confirmation

  • End-to-End Testing: Validates the entire pipeline with test documents

This example showcases the agent's ability to orchestrate complex workflows involving multiple queues, engines, schemas, automated hooks with custom logic, and intelligent document routing - all from a single conversational prompt.

Repository Structure

This repository contains four standalone Python packages:

Each package can be installed and used independently or together for complete functionality.

Quick Start

# Install and run (fastest)
uv pip install rossum-agent[api]
export ROSSUM_API_TOKEN="your-token"
export ROSSUM_API_BASE_URL="https://api.elis.rossum.ai/v1"
rossum-agent-api

Or with Docker:

git clone https://github.com/stancld/rossum-agents.git && cd rossum-agents
echo "ROSSUM_API_TOKEN=your-token" > .env
echo "ROSSUM_API_BASE_URL=https://api.elis.rossum.ai/v1" >> .env
docker-compose up rossum-agent

Installation & Usage

Prerequisites: Python 3.12+, Rossum account with API credentials

Docker Compose (Recommended)

Best for: Local development and quick testing

git clone https://github.com/stancld/rossum-agents.git
cd rossum-agents

# Create .env file with required variables
cat > .env << EOF
ROSSUM_API_TOKEN=your-api-token
ROSSUM_API_BASE_URL=https://api.elis.rossum.ai/v1
ROSSUM_MCP_MODE=read-write
AWS_PROFILE=default
AWS_DEFAULT_REGION=us-east-1
EOF

# Run the agent API
docker-compose up rossum-agent-api

Redis is included in the compose stack and used for logging. View logs with:

redis-cli LRANGE logs:$(date +%Y-%m-%d) 0 -1

From Source

Best for: Development, customization, contributing

git clone https://github.com/stancld/rossum-agents.git
cd rossum-agents

# Install all packages with all features
uv sync --all-extras

# Set up environment variables
export ROSSUM_API_TOKEN="your-api-token"
export ROSSUM_API_BASE_URL="https://api.elis.rossum.ai/v1"
export ROSSUM_MCP_MODE="read-write"

# Run the agent
rossum-agent-api                                # REST API

For individual package details, see rossum-mcp/README.md, rossum-agent/README.md, and rossum-deploy/README.md.

MCP Server with Claude Desktop

Best for: Interactive use with Claude Desktop

Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "rossum": {
      "command": "python",
      "args": ["/path/to/rossum-mcp/rossum_mcp/server.py"],
      "env": {
        "ROSSUM_API_TOKEN": "your-api-token",
        "ROSSUM_API_BASE_URL": "https://api.elis.rossum.ai/v1",
        "ROSSUM_MCP_MODE": "read-write"
      }
    }
  }
}

Or run standalone: rossum-mcp

AI Agent Interfaces

# REST API (from source)
rossum-agent-api

The agent includes file writing tools and Rossum integration via MCP. See examples/ for complete workflows.

Agent Skills & Sub-Agents

The Rossum Agent includes specialized capabilities for complex workflows:

Skills - Domain-specific instructions loaded on-demand via load_skill:

SkillPurpose
rossum-deploymentDeploy configuration changes safely via sandbox with before/after diff
schema-patchingAdd, update, or remove individual schema fields
schema-pruningRemove unwanted fields from schema in one call
organization-setupSet up Rossum for new customers with regional templates
ui-settingsUpdate queue UI settings without corrupting structure
hooksHook templates, token_owner, testing, debugging
txscriptTxScript language reference for formula fields, serverless functions, and rule trigger conditions
rules-and-actionsCreate validation rules with TxScript conditions and actions
formula-fieldsCreate/configure formula fields with TxScript
reasoning-fieldsCreate AI-powered reasoning fields with prompt + context

Sub-Agents - Opus-powered components for complex iterative tasks:

Sub-AgentInvoked ViaPurpose
Knowledge Basesearch_knowledge_base(query)Search Rossum docs with Opus-powered analysis
Schema Creationcreate_schema_with_subagent(...)Create new schemas via Opus sub-agent
Schema Patchingpatch_schema_with_subagent(schema_id, changes)Programmatic bulk schema modifications

See the full documentation for details.

MCP Tools

The MCP server provides 67 tools organized into categories:

CategoryToolsDescription
Document Processing7Upload, retrieve, update, confirm, delete annotations
Queue Management9Create, configure, delete, and list queues
Schema Management8Define, modify, and delete field structures
Engine Management6Configure extraction and splitting engines
Extensions (Hooks)9Webhooks, serverless functions
Rules & Actions6Business rules with triggers and actions
Workspace Management4Organize and delete workspaces
Organization Groups2View license groups across organizations
Organization Limits1Email sending limits and usage counters
User Management5Create, update, list users and roles
Relations4Annotation and document relations
Email Templates3Automated email responses
MCP Mode & Discovery3Get/set mode, tool catalog

See rossum-mcp/README.md for the tool list and rossum-mcp/TOOLS.md for detailed API documentation.

Documentation

Resources

Development

# Install with all development dependencies
uv pip install -e rossum-mcp[all] -e rossum-agent[all]

# Run tests
pytest

# Run regression tests (validates agent behavior)
pytest regression_tests/ -v -s

# Lint and type check
pre-commit run --all-files

See regression_tests/README.md for the agent quality evaluation framework.

License

MIT License - see LICENSE for details

Contributing

Contributions welcome! See individual package READMEs for development guidelines.

Related Servers