Rossum MCP Server & Rossum Agent

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

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?

Example 1: Organization Setup

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.

Example 2: Hook Analysis & Documentation

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.

Example 3: Aurora Splitting & Sorting Demo

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 and two Node.js packages:

• rossum-mcp/ - MCP server for Rossum API integration with AI assistants
• rossum-agent/ - Specialized AI agent toolkit with REST API
• rossum-agent-client/ - Typed Python client for the Rossum Agent API
• rossum-agent-client-ts/ - Typed TypeScript client for the Rossum Agent API
• rossum-deploy/ - Minimalistic pull/diff/push deployment tool (lightweight alternative to deployment-manager)
• rossum-agent-tui/ - Terminal UI for development and testing (Node.js)

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:

Show skills and sub-agents

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

Skill	Purpose
schema-patching	Add, update, or remove individual schema fields
python-execution	Constrained Python snippets, schema export of bulky structured outputs
ui-settings	Update queue UI settings without corrupting structure
hooks	Hook templates, token_owner, testing, debugging
txscript	TxScript language reference for formula fields, serverless functions, and rule trigger conditions
rules-and-actions	Create validation rules with TxScript conditions and actions
formula-fields	Create/configure formula fields with TxScript
reasoning-fields	Create AI-powered reasoning fields with prompt + context
lookup-fields	Create/configure lookup fields backed by Master Data Hub datasets

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

Sub-Agent	Invoked Via	Purpose
Knowledge Base	search_knowledge_base(query)	Search Rossum docs with Opus-powered analysis
Schema Patching	patch_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:

Category	Description
Read Layer	Get any entity by ID or search/list with typed filters
Delete Layer	Unified delete for any supported entity by ID
Document Processing	Upload documents, retrieve content, update/confirm/copy annotations
Queue Management	Create, configure queues (including from templates)
Schema Management	Define, modify, patch, and prune field structures
Engine Management	Configure extraction and splitting engines
Extensions (Hooks)	Webhooks, serverless functions, template-based creation, testing
Rules & Actions	Business rules with TxScript triggers and actions
Workspace Management	Create workspaces
Organization & Users	Feature flags, user creation and updates
Email Templates	Automated email responses
MCP Mode	Get/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

• Full Documentation - Complete guides and API reference
• MCP Server README - MCP server setup and tools
• Agent README - Agent toolkit and UI usage
• Deploy README - Deployment tool usage
• Examples - Sample workflows and use cases

Resources

• Rossum API - Official API documentation
• Model Context Protocol - MCP specification
• Rossum SDK - Python SDK
• Deployment Manager (PRD2) - Full-featured deployment CLI

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.