Ibm Openpages Local MCP Server
An experimental local Model Context Protocol (MCP) server that enables AI agents to securely interact with IBM OpenPages GRC platform through a standardized interface.
Ask AI about Ibm Openpages Local MCP Server
Powered by Claude · Grounded in docs
I know everything about Ibm Openpages Local MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
*** A new version of OpenPages Model Context Protocol (MCP) server is released : https://github.com/IBM/ibm-openpages-mcp-server). This page will be sunset as on July 22 2026. ***
OpenPages Local MCP Server
A local Model Context Protocol (MCP) server that enables AI agents to securely interact with IBM OpenPages GRC platform through a standardized interface.
Overview
This project provides a local server that implements the Model Context Protocol (MCP) to interact with IBM OpenPages. It allows AI agents to perform operations on OpenPages objects like issues and controls through a standardized interface. For more information on MCP, visit the official documentation.
Architecture

The OpenPages MCP Server is designed to run locally alongside AI agents and communicates with them via Standard Input/Output (STDIO). This architecture offers several advantages:
-
Local Execution: The server runs on the same machine as the agent, eliminating the need for remote server deployment and reducing latency.
-
STDIO Communication: The server uses STDIO for communication with agents, which is a simple, reliable, and language-agnostic protocol. This allows the server to be easily integrated with various AI agents regardless of their implementation language.
-
JSON-RPC Protocol: The server implements the JSON-RPC protocol over STDIO, enabling structured communication between the agent and the server. The agent sends JSON-RPC requests to the server, which processes them and returns JSON-RPC responses.
-
Secure Connection to OpenPages: While the server communicates with agents locally via STDIO, it establishes secure connections to the OpenPages instance using authentication credentials (API key or username/password).
-
Tool-based Interface: The server exposes a set of tools that agents can use to interact with OpenPages, abstracting away the complexity of the OpenPages API and providing a consistent interface.
-
Platform Compatibility: Some AI platforms, including IBM watsonx.orchestrate, specifically support local MCP servers rather than remote ones. This local architecture ensures compatibility with these platforms, making it the preferred approach for integrating OpenPages with enterprise AI systems.
This architecture makes the OpenPages MCP Server ideal for integration with various AI agents, including watsonx assistant, Claude Desktop, and other MCP-compatible agents.
Features
- Dynamic Object Type Support: Extensible architecture that supports multiple OpenPages object types (Issues, Controls, Risks, and more) through a configuration-driven approach
- CRUD Operations: Create, update, query, and delete operations for all configured object types
- Dynamic Schema Generation: Automatic schema generation based on OpenPages object type definitions
- Flexible Authentication: Support for both basic and bearer authentication methods
- Development-Friendly: Configurable SSL verification for development environments
- Configuration-Based: Easy addition of new object types through JSON configuration without code changes
Dynamic Object Type Architecture
The OpenPages MCP Server uses a dynamic, configuration-driven approach to support multiple OpenPages object types. This architecture allows you to easily extend the server to support new object types without modifying the core code.
Configuration File: object_types.json
The server uses a JSON configuration file to define the object types it supports. Each object type configuration includes:
{
"object_types": [
{
"type_id": "SOXControl", // OpenPages object type ID
"tool_prefix": "control", // Prefix for tool names (e.g., create_control)
"display_name": "Control", // Human-readable name
"path_prefix": "Controls", // API path prefix
"status_field": "OPSS-Ctl:Status" // Status field identifier
},
{
"type_id": "SOXIssue",
"tool_prefix": "issue",
"display_name": "Issue",
"path_prefix": "Issue",
"status_field": "OPSS-Iss:Status"
},
{
"type_id": "SOXRisk",
"tool_prefix": "risk",
"display_name": "Risk",
"path_prefix": "Risk",
"status_field": "OPSS-Risk:Status"
}
]
}
How It Works
- Automatic Tool Generation: The server reads
object_types.jsonat startup and automatically generates MCP tools for each configured object type - Schema Discovery: For each object type, the server queries OpenPages to retrieve the field schema and generates appropriate tool parameters
- Consistent Interface: All object types follow the same CRUD pattern (create, update, query, delete), ensuring a consistent interface
- Easy Extension: To add support for a new object type, simply add a new entry to
object_types.jsonwith the appropriate configuration
Adding New Object Types
To add support for a new OpenPages object type:
- Add a new entry to
object_types.jsonwith the object type details - Restart the MCP server
- The server will automatically generate the necessary tools for the new object type
Example for adding a new "Action" object type:
{
"type_id": "SOXAction",
"tool_prefix": "action",
"display_name": "Action",
"path_prefix": "Actions",
"status_field": "OPSS-Act:Status"
}
Prerequisites
- Python 3.11+
- Access to an IBM OpenPages instance
- Authentication credentials (username/password or API key)
Installation
-
Clone this repository:
git clone https://github.com/IBM/ibm-openpages-local-mcp-server cd ibm-openpages-local-mcp-server -
Create and activate a Python virtual environment (recommended best practice):
On macOS/Linux:
python3 -m venv venv source venv/bin/activateOn Windows:
python -m venv venv venv\Scripts\activate -
Install dependencies:
pip install -r requirements.txt -
Configure environment variables:
cp .env.example .envEdit the
.envfile with your OpenPages connection details.
Configuration
The following environment variables can be configured in the .env file:
OpenPages Configuration
OPENPAGES_BASE_URL: URL of your OpenPages instanceOPENPAGES_AUTHENTICATION_TYPE: Authentication type (basicorbearer)- Use
basicfor on-premises installations - Use
bearerfor SaaS deployments (IBM Cloud or MCSP)
- Use
OPENPAGES_USERNAME: Username for basic authenticationOPENPAGES_PASSWORD: Password for basic authenticationOPENPAGES_APIKEY: API key for bearer authentication- For IBM Cloud: Standard IBM Cloud API key
- For MCSP: Base64-encoded client_id:client_secret
OPENPAGES_AUTHENTICATION_URL: Authentication URL for bearer authentication- For IBM Cloud:
https://iam.cloud.ibm.com/identity/token - For MCSP:
https://account-iam.platform.saas.ibm.com/api/2.0/services/{service_id}/apikeys/token
- For IBM Cloud:
Server Configuration
DEBUG: Enable debug mode (TrueorFalse)SSL_VERIFY: Enable SSL verification (TrueorFalse)- Set to
Truefor SaaS deployments (recommended for production) - Set to
Falsefor on-premises local Fyre-based Docker installations
- Set to
LOG_LEVEL: Logging level (INFO,DEBUG,WARNING,ERROR)PORT: Server port (default: 8000)HOST: Server host (default: 0.0.0.0)
Usage
Starting the MCP Server
- Start the MCP server by CLI:
python start_mcp.py
For debug mode:
python start_mcp.py --debug
Local Testing Options
You can test the MCP server locally using one of the following methods:
1. Using Python CLI with JSON-RPC Requests
You can send JSON-RPC requests directly to the server and receive responses:
-
Start the MCP server:
python start_mcp.py -
In the same terminal, send JSON-RPC requests. For example, to list available tools:
{"method":"tools/list","params":{"_meta":{"progressToken":1}},"jsonrpc":"2.0","id":1} -
Press Enter to send the request. The server will respond with the tools definitions.
-
You can test other JSON-RPC methods such as:
- List tools:
{"method":"tools/list","params":{"_meta":{"progressToken":1}},"jsonrpc":"2.0","id":1} - Call a tool:
{"method":"tools/call","params":{"name":"tool_name","arguments":{}},"jsonrpc":"2.0","id":2}
- List tools:
2. Using MCP Inspector UI
For a more user-friendly testing experience, you can use the MCP Inspector UI (requires Node.js):
-
Run the following command from the base folder of the MCP Server:
npx @modelcontextprotocol/inspector@latest -
The MCP Inspector UI will open in your browser. Configure it with the following settings:
- Transport Type: STDIO
- Command: Python
- Arguments: start_mcp.py
-
Click on "Connect", and the MCP Inspector will start the MCP server and connect to it via STDIO.
-
Go to the "Tools" tab and click on "List Tools" to see all available tools.
-
Click on any tool, fill in the required fields, and click on "Run Tool" to test the tool.
-
The tool runs and result is fetched.
Available Tools
The server dynamically generates MCP tools based on the object types configured in object_types.json. For each configured object type, the following tools are automatically created:
Standard CRUD Operations (per Object Type)
For each object type (e.g., Issue, Control, Risk), the following tools are generated:
-
create_{object_type}: Create a new object in OpenPages- Example:
create_issue,create_control,create_risk
- Example:
-
update_{object_type}: Update an existing object- Example:
update_issue,update_control,update_risk
- Example:
-
query_{object_type}s: Search for objects with filtering options- Example:
query_issues,query_controls,query_risks
- Example:
-
delete_{object_type}: Delete an object by ID- Example:
delete_issue,delete_control,delete_risk
- Example:
Currently Configured Object Types
Based on the default object_types.json configuration, the following tools are available:
Issue Management
create_issue: Create a new issue in OpenPagesupdate_issue: Update an existing issuequery_issues: Search for issues with filtering optionsdelete_issue: Delete an issue by resource ID
Control Management
create_control: Create a new control in OpenPagesupdate_control: Update an existing controlquery_controls: Search for controls with filtering optionsdelete_control: Delete a control by resource ID
Risk Management
create_risk: Create a new risk in OpenPagesupdate_risk: Update an existing riskquery_risks: Search for risks with filtering optionsdelete_risk: Delete a risk by resource ID
Utility
echo: Simple echo tool for testing connectivity
Integration with IBM watsonX orchestrate
Prerequisites
- OpenPages SaaS instance and an APIKey with OpenPages access
- IBM watsonX orchestrate instance and an APIKey with watsonx orchestrate access
- A running local environment of watsonx Agent Development Kit (ADK) - Check out the getting started with ADK tutorial if you don't have an active instance
- Read Access to OpenPages MCP Server repo - https://github.com/IBM/ibm-openpages-local-mcp-server
Steps to Import MCP Tools to watsonX orchestrate
-
Checkout the OpenPages MCP Server code to your local machine:
git clone https://github.com/IBM/ibm-openpages-local-mcp-server cd ibm-openpages-local-mcp-server -
Create a
.envfile in the base folder by copying the content from.env.example:cp .env.example .env -
Add the following configuration values in the
.envfile:# OpenPages Configuration OPENPAGES_BASE_URL=<Valid OpenPages SaaS URL> OPENPAGES_APIKEY=<APIKey with access to openpages instance> OPENPAGES_AUTHENTICATION_TYPE=bearer # For IBM Cloud: OPENPAGES_AUTHENTICATION_URL=https://iam.cloud.ibm.com/identity/token # For MCSP: # OPENPAGES_AUTHENTICATION_URL=https://account-iam.platform.saas.ibm.com/api/2.0/services/{service_id}/apikeys/token # Keep other configs as-is -
Load the MCP tools into your watsonx orchestrate instance using the following command (replace placeholders with your values):
orchestrate toolkits add \ --kind mcp \ --name "Name of the server" \ --description "MCP tools for OpenPages integration" \ --package-root "Base folder of the code" \ --command "python start_mcp.py" \ --tools "*" -
Enter the APIKey when prompted, and the tools will be loaded to the watsonx orchestrate instance.
Note: Sometimes watsonx tools import will give error like "requests.exceptions.HTTPError: 500 Server Error: Internal Server Error".In such cases, retry with a new toolName). If still retry fails, then remove the contents of requirements.txt and save it and again perform the tool import with a new name.
Creating an Agent with OpenPages MCP Tools
-
In the watsonx Orchestrate "Agent Builder" screen, create a new Agent.
-
Fill in the name and description:
- Name: IBM OpenPages Agent (or any name you prefer)
- Description: An intelligent OpenPages agent equipped with tools to perform CRUD operations on key GRC entities such as Issues, Controls, Risks, and Actions. It can create, retrieve, update, and delete records efficiently while ensuring data integrity and adherence to OpenPages data models and business rules.
-
Go to the Toolset section, click "Add tool" to add the MCP tools imported in the previous steps. Add all 6 OpenPages tools.
-
Go to the Behavior section and define how the agent should react to requests with the following instructions:
For OpenPages operations: - Use openpages-mcp-tools:create_issue, update_issue, query_issues for issue management - Use openpages-mcp-tools:create_control, update_control, query_controls for control management - Format user input according to tool schema requirements Field name handling when working with OpenPages fields: 1. Field Naming Conventions: - Full technical field name: The complete identifier with prefix (e.g., "OPSS-Ctl:Status") - User-friendly label: The human-readable name (e.g., "Status") found in the schema as x-label - Simple name: The field name without prefix (e.g., "Status") 2. Field Name Resolution: - Users will typically provide the user-friendly label - Always convert user-provided labels to the appropriate full technical field name when passing to MCP tools - Use the following resolution order: a. Exact match with full technical field name b. Case-insensitive match with full technical field name c. Match with user-friendly label d. Match with simple name (without prefix) 3. Handling Ambiguity: - If a label is ambiguous (could refer to multiple fields): a. Inform the user about the ambiguity b. List the possible full technical field names that match c. Ask the user to specify which full technical field name they want to use - Example: "The label 'Status' is ambiguous and could refer to multiple fields: 'OPSS-Ctl:Status' or 'OPSS-Iss:Status'. Please specify which field you want to use." 4. Feedback: - When resolving field names, provide transparent feedback about which technical field is being used - Example: "Using field 'OPSS-Ctl:Status' for the label 'Status'" Technical considerations: - Start MCP server only once per session - Provide detailed error information for debugging when tools fail -
Deploy the Agent.
Testing the Agent
You can test the agent either from the Preview right pane or by selecting the agent in the watsonx Orchestrate home page and chatting with it. Here are some sample prompts to test different OpenPages Tools:
Issue Management Examples
1. Create Issue (create_issue tool)
Create an issue in OpenPages with the following details
Name - Issue for business Entity ABC Ltd
Description - Mitigating infra risks
Primary parent id - 7599
Issue Owner - jayasankar.sreedharan@ibm.com
Priority - Medium
Issue Status - Open
Issue Type - Design Effectiveness
2. Update Issue (update_issue tool)
Update the issue with Resource ID - 14008 and name - Issue for business Entity ABC Ltd, with the following updated properties
Description - Mitigating financial issues
Priority - High
Issue Type - Control Activity Missing
3. Query Issue (query_issues tool)
Get the issue in openpages with name - 'Issue for business Entity ABC Ltd' and show the below properties
Name
Description
Primary parent id
Issue Owner
Priority
Issue Status
Issue Type
4. Delete Issue (delete_issue tool)
Delete the issue with id 14008
Control Management Examples
5. Create Control (create_control tool)
Create a control in OpenPages with the following details
Name - Control for business Entity ABC Ltd
Description - Mitigating infra risks
Control Owner -
Design Effectiveness - Not Determined
Operating Effectiveness - Effective
Control Type - Detective
Frequency - Daily
Primary parent id - 8182
6. Update Control (update_control tool)
Update the control with Resource ID - 14011 and name - 'Control for business Entity ABC Ltd', with the following updated properties
Control Owner - Jayasankar.Sreedharan@ibm.com
7. Query Control (query_controls tool)
Get the control in openpages with name - 'Control for business Entity ABC Ltd' and show the below properties
Name
Description
Control Owner
Design Effectiveness
Operating Effectiveness
Control Type
Frequency
Primary parent id
8. Delete Control (delete_control tool)
Delete the control with id 14011
Risk Management Examples
9. Create Risk (create_risk tool)
Create a risk in OpenPages with the following details
Name - Risk for business Entity ABC Ltd
Description - Mitigating openpages risks
Status - Awaiting Assessment
Owner - Jayasankar.Sreedharan@ibm.com
Assessment Method - Qualitative
Basel Risk Category - External Fraud
Primary parent id - 5492
Domain - Technology
10. Update Risk (update_risk tool)
Update the risk with Resource ID - 14045 and name - 'Risk for business Entity ABC Ltd', with the following updated properties
Description - Mitigating financial risks
11. Query Risk (query_risks tool)
Get the risk in openpages with name - 'Risk for business Entity ABC Ltd' and show the below properties
Name
Description
Status
Owner
Assessment Method
Basel Risk Category
Primary parent id
12. Delete Risk (delete_risk tool)
Delete the risk with id 14045
OpenPages Local MCP - WatsonX Orchestrate High Level Architecture - User Flow

Security Considerations
- Store credentials securely and never commit them to version control
- Enable SSL verification in production environments
- Use bearer authentication with API keys when possible
- Restrict access to the server to trusted networks
Troubleshooting
- Check the logs for detailed error messages
- Verify your OpenPages connection details
- Ensure your authentication credentials are correct
- For SSL certificate issues in development, you can set
SSL_VERIFY=False(not recommended for production)
OpenPages MCP Server Roadmap
The OpenPages MCP Server is continuously evolving to provide enhanced capabilities for AI integration with IBM OpenPages. Below is the roadmap outlining planned future developments:
Current Beta Version
The current beta version of the OpenPages MCP Server is implemented as a local server with:
- CRUD operations for key entities (Issues and Controls)
- Local execution model with STDIO communication
- Integration with watsonx.orchestrate and other MCP-compatible agents
Short-term Enhancements
- Enhanced Query Capabilities: Improve filtering, sorting, and relationship traversal in query tools
- Use-Case Level Tools: Develop higher-level tools that encapsulate common business processes and workflows
Long-term Vision
- Remote MCP Server: Develop support for remote MCP server deployment that can be independently scaled alongside OpenPages instances
- HTTP Streaming Communication: Implement streamable HTTP communication with agents for improved performance and scalability
- Advanced Analytics Integration: Tools for integrating OpenPages data with analytics and reporting capabilities
This roadmap represents our commitment to making OpenPages data and functionality more accessible to AI agents while maintaining security, performance, and usability.
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Support
For issues and questions, please use the GitHub Issues page.
Acknowledgments
- Built with the Model Context Protocol
- Integrates with IBM OpenPages GRC platform
- Compatible with IBM watsonx.orchestrate and other MCP-compatible AI agents
