Opus MCP Server

Model Context Protocol (MCP) server for the Opus Job Operator API. This server provides tools to programmatically interact with Opus workflows, including job initiation, execution, monitoring, and file uploads.

Quick Start: See QUICKSTART.md for 3-minute setup!
Installation: See INSTALL.md for detailed instructions
Distribution: See DISTRIBUTION.md for sharing options

Features

• Workflow Management: Get workflow details and schemas
• Job Operations: Initiate, execute, and monitor jobs
• File Handling: Generate presigned URLs for secure file uploads
• Monitoring: Check job status, retrieve results, and view audit logs

Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Set up environment variables:

cp .env.example .env
# Edit .env and add your OPUS_SERVICE_KEY

Getting Your API Key

1. Navigate to the Opus platform
2. Click My Organization at the top
3. Click the gear icon next to your Organization's name
4. Select API Keys from the settings menu
5. Click + Generate API Key
6. Copy the key (shown only once) and add to .env file

Configuration

For Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opus": {
      "command": "node",
      "args": ["/absolute/path/to/function1 hackathon/build/index.js"],
      "env": {
        "OPUS_SERVICE_KEY": "your_service_key_here"
      }
    }
  }
}

For Other MCP Clients

Use the built executable with environment variable:

OPUS_SERVICE_KEY=your_key node build/index.js

Available Tools

1. get_workflow_details

Get workflow details including the jobPayloadSchema that defines required inputs.

Parameters:

• workflowId (string, required): The workflow ID from Opus

Returns: Full workflow details including schema, execution estimation, and input requirements

2. initiate_job

Create a new job instance for a workflow.

Parameters:

• workflowId (string, required): The workflow ID
• title (string, required): Job title
• description (string, required): Job description

Returns: jobExecutionId needed for subsequent operations

3. generate_file_upload_url

Generate presigned URLs for secure file uploads.

Parameters:

• fileExtension (string, required): File extension with dot (e.g., .pdf, .jpeg, .png, .docx)
• accessScope (string, optional): Access scope - all, user, workspace, or organization (default)

Returns:

• presignedUrl: Use for uploading file via PUT request
• fileUrl: Use this URL in job execution payload

Supported File Types: .jpeg, .png, .jpg, .pdf, .docx, .csv, .xls, .xlsx, .txt, .json, .html, .xml

4. execute_job

Execute a job with populated input values.

Parameters:

• jobExecutionId (string, required): From initiate_job response
• jobPayloadSchemaInstance (object, required): Job inputs structured according to workflow schema

Example jobPayloadSchemaInstance:

{
  "workflow_input_we4tej0ly": {
    "value": "API Test Project",
    "type": "str"
  },
  "workflow_input_a0hk6ujuo": {
    "value": 45.8,
    "type": "float"
  },
  "workflow_input_h69vx5i4a": {
    "value": "https://files.opus.com/media/private/uploaded/media_file.pdf",
    "type": "file"
  }
}

5. get_job_status

Check current job execution status.

Parameters:

• jobExecutionId (string, required): The job ID

Returns: Status - IN PROGRESS, COMPLETED, or FAILED

6. get_job_results

Retrieve results from a completed job.

Parameters:

• jobExecutionId (string, required): The job ID

Returns: Job results including output files and data (only works when status is COMPLETED)

7. get_job_audit_log

Get detailed audit log of job execution.

Parameters:

• jobExecutionId (string, required): The job ID

Returns: Timestamped log of all system actions

Workflow Example

1. Get workflow details to understand required inputs
   → get_workflow_details(workflowId: "B9uGJfZ3CFwOdMKH")

2. (If needed) Generate file upload URLs
   → generate_file_upload_url(fileExtension: ".pdf")
   → Upload file to presignedUrl using PUT request

3. Initiate a job
   → initiate_job(workflowId, title, description)
   → Save jobExecutionId

4. Execute the job with inputs
   → execute_job(jobExecutionId, jobPayloadSchemaInstance)

5. Monitor status
   → get_job_status(jobExecutionId)

6. Get results when complete
   → get_job_results(jobExecutionId)

7. (Optional) View audit log
   → get_job_audit_log(jobExecutionId)

Development

Watch mode for development:

npm run watch

API Documentation

For complete API details, see the markdown files in the root directory:

• opus-00-get-workflow-details.md - Workflow schema retrieval
• opus-03-initiate-job.md - Job initiation
• opus-04-uploading-files-for-job-inputs.md - File uploads
• opus-05-execute-job.md - Job execution
• opus-06-get-job-execution-status.md - Status monitoring
• opus-07-get-job-execution-results.md - Results retrieval
• opus-08-job-audit-log.md - Audit logs

Base URL

All requests are made to: https://operator.opus.com

Troubleshooting

Error: OPUS_SERVICE_KEY environment variable is required

• Ensure your .env file exists with the correct key, or
• Set the environment variable in your MCP client configuration

Error: Authentication failed

• Verify your service key is valid and not expired
• Check that the key has proper permissions in Opus

File upload issues

• Ensure file extension matches the actual file type
• Use PUT request without authentication headers for presigned URL
• Verify file size limits (if any) in Opus documentation

License

MIT