Skip to content

vperrinfr/OpenPages_MCP

BranchesTags

Repository files navigation

IBM OpenPages MCP Server

A Model Context Protocol (MCP) server that provides access to IBM OpenPages REST API V2 (version 9.1). This server enables AI assistants to interact with IBM OpenPages GRC (Governance, Risk, and Compliance) platform.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     AI Platforms (MCP Clients)                  │
├─────────────────┬─────────────────┬─────────────────────────────┤
│  Claude Desktop │ Watsonx         │ Langflow                    │
│                 │ Orchestrate     │ (Python MCP Client)         │
└────────┬────────┴────────┬────────┴────────┬────────────────────┘
         │                 │                 │
         │    MCP Protocol (stdio/JSON-RPC)  │
         │                 │                 │
         └─────────────────┼─────────────────┘
                           │
                           ▼
         ┌─────────────────────────────────┐
         │   IBM OpenPages MCP Server      │
         │   (Node.js/TypeScript)          │
         │                                 │
         │  • 18 MCP Tools                 │
         │  • Authentication Handler       │
         │  • Error Management             │
         │  • Request/Response Mapping     │
         └────────────┬────────────────────┘
                      │
                      │ HTTPS/REST API
                      │
                      ▼
         ┌─────────────────────────────────┐
         │   IBM OpenPages Platform        │
         │   REST API V2 (v9.1)            │
         │                                 │
         │  • GRC Objects (CRUD)           │
         │  • Query & Search               │
         │  • Workflows                    │
         │  • Configuration                │
         │  • Associations                 │
         └─────────────────────────────────┘

Key Components

  • MCP Server: Implements Model Context Protocol, exposing 18 tools for OpenPages operations
  • AI Platforms: Connect via native MCP protocol (stdio communication)
  • OpenPages API: Backend GRC platform accessed via REST API V2
  • Authentication: Supports Basic Auth, Bearer Token, and API Key methods

Features

This MCP server exposes the following IBM OpenPages capabilities:

GRC Objects Management

  • Get Object: Retrieve detailed information about GRC objects
  • Create Object: Create new GRC objects (Issues, Risks, Controls, etc.)
  • Update Object: Modify existing GRC objects
  • Delete Object: Soft delete GRC objects

Query & Search

  • Query: Execute SQL-like queries on GRC content
  • Search: Global search across all GRC content with ranking

Object Types & Metadata

  • Get Object Types: List all available GRC object types
  • Get Object Type: Get detailed schema for a specific type

Folders & Organization

  • Get Folders: Access folder hierarchy
  • Get Folder Resources: List contents of folders

Workflows

  • Get Workflows: List workflow definitions
  • Get Workflow Instance: Get workflow status
  • Transition Workflow: Move objects through workflow states

Configuration

  • Tags: Manage and retrieve tags
  • Currencies: Access currency configurations
  • Profiles: Get user profile information
  • Processes: Monitor long-running processes

Associations

  • Get Associations: Retrieve parent/child relationships between objects

Installation

  1. Clone this repository
  2. Install dependencies:
npm install
  1. Build the TypeScript code:
npm run build

Configuration

Configure the server using environment variables:

# Required: OpenPages server URL
export OPENPAGES_BASE_URL="https://your-server.com/opgrc/api"

# Authentication Option 1: Basic Auth
export OPENPAGES_USERNAME="your-username"
export OPENPAGES_PASSWORD="your-password"

# Authentication Option 2: Bearer Token
export OPENPAGES_BEARER_TOKEN="your-jwt-token"

Usage

This server uses the Model Context Protocol (MCP) standard and can be integrated with multiple AI platforms using the same native MCP protocol.

MCP Native Integration (Recommended)

All platforms use the same MCP configuration format:

{
  "mcpServers": {
    "openpages": {
      "command": "node",
      "args": ["/path/to/mcp-openpages-server/dist/index.js"],
      "env": {
        "OPENPAGES_BASE_URL": "https://your-server.com/opgrc/api",
        "OPENPAGES_USERNAME": "your-username",
        "OPENPAGES_PASSWORD": "your-password"
      }
    }
  }
}

Supported Platforms

1. Claude Desktop

Configuration file location:

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

Add the MCP configuration above to this file.

2. Watsonx Orchestrate

MCP Native Integration:

If Watsonx Orchestrate supports MCP protocol, use the same configuration as Claude Desktop. Consult IBM Watsonx documentation for the configuration file location.

Alternative: If MCP is not yet supported, see MCP_NATIVE_INTEGRATION.md for Python MCP client implementation.

3. Langflow

MCP Native Integration:

Use the Python MCP client provided in MCP_NATIVE_INTEGRATION.md to connect Langflow to the MCP server. This allows Langflow to use all 18 MCP tools natively.

Example:

from mcp_client import create_openpages_tools
tools, client = create_openpages_tools()
# Use tools in your Langflow components

4. Any MCP-Compatible Client

Any application that supports the Model Context Protocol can connect to this server using the standard MCP configuration.

Alternative: REST API Wrapper

For platforms that don't support MCP yet, a REST API wrapper is available:

npm run rest  # Starts REST API on port 3000

See INTEGRATION_GUIDE.md for REST API details.

Available Tools

openpages_get_object

Get a GRC Object by ID or path.

Parameters:

  • id (required): Object ID or path
  • include_associations: Include parent/child associations (none/both/parent/child)
  • include_workflow: Include workflow information (boolean)

Example:

Get object with ID 12345 including all associations

openpages_create_object

Create a new GRC Object.

Parameters:

  • type_definition_id (required): Object type (e.g., "SOXIssue")
  • name (required): Object name
  • description: Object description
  • primary_parent_id: Parent object ID or path
  • fields: Array of field objects with id/name and value

Example:

Create a new SOXIssue named "Security Vulnerability" with description "Critical security issue found"

openpages_update_object

Update an existing GRC Object.

Parameters:

  • id (required): Object ID or path
  • name: Updated name
  • description: Updated description
  • fields: Array of fields to update

openpages_delete_object

Soft delete a GRC Object.

Parameters:

  • id (required): Object ID or path

openpages_query

Execute SQL-like queries on GRC content.

Parameters:

  • statement (required): SQL-like query (e.g., "SELECT [Name] FROM [SOXBusEntity]")
  • offset: Pagination offset (default: 0)
  • limit: Maximum results
  • case_insensitive: Case-insensitive string comparison (boolean)

Example:

Query all business entities: SELECT [Name], [Description] FROM [SOXBusEntity] WHERE [Name] LIKE '%Finance%'

openpages_search

Global search across GRC content.

Parameters:

  • q (required): Search terms
  • types: Comma-delimited list of object types to search
  • range: Result range (e.g., "0-9")

Example:

Search for "audit findings" in SOXIssue and SOXRisk types

openpages_get_object_types

List all GRC Object Types.

Parameters:

  • include_field_definitions: Include field definitions (boolean)

openpages_get_object_type

Get detailed information about a specific Object Type.

Parameters:

  • type_id (required): Object Type ID or system name
  • include_field_definitions: Include field definitions (boolean)

openpages_get_folders

Get the root folder resource.

openpages_get_folder

Get specific folder information.

Parameters:

  • folder_id (required): Folder ID

openpages_get_folder_resources

Get all resources in a folder.

Parameters:

  • folder_id (required): Folder ID
  • include_containees: Resource types (folder/grcobject/both)
  • offset: Pagination offset
  • limit: Maximum results per page

openpages_get_workflows

Get workflow process definitions.

Parameters:

  • object_type: Filter by object type

openpages_get_workflow_instance

Get workflow instance data.

Parameters:

  • id (required): Workflow instance ID

openpages_transition_workflow

Transition a GRC object through workflow.

Parameters:

  • id (required): Workflow instance ID
  • transition (required): Transition action name

openpages_get_associations

Get object associations.

Parameters:

  • id (required): Object ID or path
  • association_type: Filter by parent/child

openpages_get_tags

Get system tags.

Parameters:

  • only_enabled: Return only enabled tags (boolean)

openpages_get_currencies

Get configured currencies.

Parameters:

  • only_enabled: Return only enabled currencies (boolean)

openpages_get_profiles

Get all user profiles.

openpages_get_processes

Get process instances.

Parameters:

  • process_type_id: Filter by process type
  • status: Filter by status
  • created_by: Filter by creator

Example Interactions

Creating a Risk Object

Create a new SOXRisk object named "Data Breach Risk" with high severity in the IT Security folder

Querying Issues

Query all open issues created in the last 30 days with high priority

Searching for Controls

Search for all controls related to "access management" in the SOXControl type

Managing Workflows

Get the workflow status for issue ID 12345 and transition it to "In Review" state

API Coverage

This MCP server implements the following IBM OpenPages REST API V2 endpoints:

  • ✅ Contents (GRC Objects) - CRUD operations
  • ✅ Query Service - SQL-like queries
  • ✅ Search Service - Global search
  • ✅ Types - Object type metadata
  • ✅ Folders - Folder management
  • ✅ Workflows - Workflow operations
  • ✅ Configuration - Tags, Currencies, Profiles
  • ✅ Associations - Object relationships
  • ✅ Processes - Long-running processes

Limitations

  • This server requires network access to your IBM OpenPages instance
  • Authentication credentials must be properly configured
  • Some operations require specific permissions in OpenPages
  • The server supports OpenPages version 9.1 (may work with other versions)

Security Considerations

  • Store credentials securely using environment variables
  • Use HTTPS for all OpenPages connections
  • Consider using bearer tokens instead of basic authentication
  • Limit MCP server access to trusted AI assistants only
  • Review OpenPages audit logs regularly

Troubleshooting

Connection Issues

  • Verify OPENPAGES_BASE_URL is correct
  • Check network connectivity to OpenPages server
  • Ensure SSL certificates are valid

Authentication Errors

  • Verify username/password or bearer token
  • Check user permissions in OpenPages
  • Ensure account is not locked

API Errors

  • Check OpenPages version compatibility
  • Review error messages in responses
  • Consult OpenPages documentation for specific error codes

Development

To run in development mode:

npm run dev

To build:

npm run build

License

MIT

Support

For issues related to:

Additional Documentation

References

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages