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 API Reference Python License: MIT

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

codecov CodeQL Snyk Security CodeFactor

MCP Fully Typed 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
schema-patchingAdd, update, or remove individual schema fields
python-executionConstrained Python snippets, schema export of bulky structured outputs
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
lookup-fieldsCreate/configure lookup fields backed by Master Data Hub datasets

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 Patchingpatch_schema_with_subagent(schema_id, changes)Programmatic bulk schema modifications

See the full documentation for details.

MCP Tools

The MCP server exposes a compact, fully-typed tool surface — Pydantic models, Literal unions, and consolidated APIs built for agents:

CategoryDescription
Read LayerGet any entity by ID or search/list with typed filters
Delete LayerUnified delete for any supported entity by ID
Document ProcessingUpload documents, retrieve content, update/confirm/copy annotations
Queue ManagementCreate, configure queues (including from templates)
Schema ManagementDefine, modify, patch, and prune field structures
Engine ManagementConfigure extraction and splitting engines
Extensions (Hooks)Webhooks, serverless functions, template-based creation, testing
Rules & ActionsBusiness rules with TxScript triggers and actions
Workspace ManagementCreate workspaces
Organization & UsersFeature flags, user creation and updates
Email TemplatesAutomated email responses
MCP ModeGet/set read-only or read-write mode at runtime

See rossum-mcp/README.md for the full 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