Usage

Running the MCP Server

Start the server using:

python -m rossum_mcp.server

Or if installed as a package:

rossum-mcp

Using with MCP Clients

Claude Desktop Configuration

Configure your MCP client to use this server. For example, in Claude Desktop’s config:

{
  "mcpServers": {
    "rossum": {
      "command": "python",
      "args": ["/path/to/rossum-mcp/server.py"],
      "env": {
        "ROSSUM_API_TOKEN": "your-api-token",
        "ROSSUM_API_BASE_URL": "https://api.elis.develop.r8.lol/v1"
      }
    }
  }
}

Using with Smolagents

The Python implementation makes it easy to use with smolagents, as both use Python and can share the rossum_api package:

from smolagents import ToolCallingAgent, ManagedAgent

# Create a Rossum MCP agent
rossum_agent = ManagedAgent(
    agent=ToolCallingAgent(tools=[]),
    name="rossum",
    description="Upload and process documents using Rossum API"
)

# Use the agent
result = rossum_agent.run(
    "Upload the invoice.pdf to queue 12345 and wait for it to be processed"
)

Available Tools

upload_document

Uploads a document to Rossum for processing. Returns a task ID. Use list_annotations to get the annotation ID.

Parameters:

file_path (string, required): Absolute path to the document file
queue_id (integer, required): Rossum queue ID where the document should be uploaded

Returns:

{
  "task_id": "12345",
  "task_status": "created",
  "queue_id": 12345,
  "message": "Document upload initiated. Use `list_annotations` to find the annotation ID for this queue."
}

get_annotation

Retrieves annotation data for a previously uploaded document. Use this to check the status of a document.

Parameters:

annotation_id (integer, required): The annotation ID obtained from list_annotations
sideloads (array, optional): List of sideloads to include. Use ['content'] to fetch annotation content with datapoints

Returns:

{
  "id": "12345",
  "status": "to_review",
  "url": "https://elis.rossum.ai/api/v1/annotations/12345",
  "schema": "67890",
  "modifier": "11111",
  "document": "22222",
  "content": [...],
  "created_at": "2024-01-01T00:00:00Z",
  "modified_at": "2024-01-01T00:00:00Z"
}

list_annotations

Lists all annotations for a queue with optional filtering. Useful for checking the status of multiple uploaded documents.

Parameters:

queue_id (integer, required): Rossum queue ID to list annotations from
status (string, optional): Filter by annotation status (default: ‘importing,to_review,confirmed,exported’)

Returns:

{
  "count": 42,
  "results": [
    {
      "id": "12345",
      "status": "to_review",
      "url": "https://elis.rossum.ai/api/v1/annotations/12345",
      "document": "67890",
      "created_at": "2024-01-01T00:00:00Z",
      "modified_at": "2024-01-01T00:00:00Z"
    }
  ]
}

get_queue

Retrieves queue details including the schema_id. Use this to get the schema_id for use with get_schema.

Parameters:

queue_id (integer, required): Rossum queue ID to retrieve

Returns:

{
  "id": "12345",
  "name": "Invoices",
  "url": "https://elis.rossum.ai/api/v1/queues/12345",
  "schema_id": "67890",
  "workspace": "11111",
  "inbox": "22222",
  "created_at": "2024-01-01T00:00:00Z",
  "modified_at": "2024-01-01T00:00:00Z"
}

get_schema

Retrieves schema details including the schema content/structure. Use get_queue first to obtain the schema_id.

Parameters:

schema_id (integer, required): Rossum schema ID to retrieve

Returns:

{
  "id": "67890",
  "name": "Invoice Schema",
  "url": "https://elis.rossum.ai/api/v1/schemas/67890",
  "content": [...]
}

get_queue_schema

Retrieves the complete schema for a queue in a single call. This is the recommended way to get a queue’s schema.

Parameters:

queue_id (integer, required): Rossum queue ID

Returns:

{
  "queue_id": "12345",
  "queue_name": "Invoices",
  "schema_id": "67890",
  "schema_name": "Invoice Schema",
  "schema_url": "https://elis.rossum.ai/api/v1/schemas/67890",
  "schema_content": [...]
}