ibm/ibm-openpages-mcp-server

Purpose and Entry Points

GRC MCP Server is a Python 3.12+ Model Context Protocol adapter between AI agents and IBM OpenPages GRC. It exposes OpenPages object operations, query execution, schemas, prompts, and health/metrics over either streamable HTTP or stdio. Runtime selection begins at main.py; local execution is implemented under src/app/mcp/local/runner.py, while remote HTTP serving is assembled through src/app/mcp/remote/server_instance.py.

Transport and MCP Dispatch

Remote clients call /mcp using JSON-RPC; local MCP clients communicate over process stdin/stdout. The transport boundary normalizes MCP requests before method routing, supporting tools, resources, prompts, initialization, and shutdown.

• src/app/mcp/mcp_server.py

• src/app/mcp/request_processor.py

• src/app/mcp/remote/http_router.py

Configuration-Driven Capability Model

Environment-backed settings establish connectivity, authentication mode, server behavior, and observability. The configured OpenPages object-type catalog determines the namespace, exposed tool mode (generic ontology-based, per-type, or both), resource field filtering, and schemas presented to agents. This is the primary boundary between deployment policy and runtime capabilities.

• src/app/config/settings.py

• src/app/config/object_types.json

• src/app/mcp/schema_builder.py

Tools and OpenPages Integration

Tool handlers translate MCP tool calls into object create/update, lookup/query, delete, and association operations. Generic and type-specific tool definitions are generated from configuration and validated against discovered schemas. The query path supports OpenPages SQL-like syntax independently of object CRUD tools. The OpenPages client is the external-service boundary for REST/API calls to the configured OpenPages instance.

• src/app/mcp/tool_handlers.py

• src/app/tools/generic_object_tools.py

• src/app/tools/query_tool.py

• src/app/core/openpages_client.py

Schema Resources and Agent Guidance

The server publishes ontology discovery resources: the object-type catalog, per-type schema, and query grammar; resource-compatible tools provide fallback access for limited MCP clients. Prompt handlers supply an agent usage guide. Schema construction filters and formats OpenPages metadata according to object-type configuration, so agents can discover valid fields before issuing mutations or queries.

• src/app/mcp/resource_handlers.py

• src/app/mcp/docs/documentation_resources.py

• src/app/mcp/prompt_handlers.py

• src/docs/MCP_SERVER_PROMPT.md

Authentication and Request Context

Authentication supports configured server credentials (basic or bearer variants including IBM IAM, MCSP, and CP4D) plus per-user credentials. In user mode, request authentication is resolved in priority order from HTTP bearer token, MCP context header, opaque ticket exchange, then configured API-key header; failures do not fall back to server credentials. Context extraction also carries user and view metadata into authorization and logging boundaries.

• src/app/auth/service.py

• src/app/auth/providers.py

• src/app/auth/token_exchange.py

• src/app/mcp/context.py

Cache, Synchronization, and Operations

Schema metadata is cached to reduce OpenPages calls and can be refreshed through RabbitMQ-driven invalidation/synchronization. Remote mode additionally exposes health, readiness/liveness/startup, cache statistics, and optional Prometheus metrics. Structured logs, OpenTelemetry tracing, and metrics instrument request paths. Container deployment uses Docker Compose, with optional NGINX and a separate Prometheus/Grafana/Jaeger/Loki monitoring stack.

• src/app/cache/schema_cache_manager.py

• src/app/cache/rabbitmq_client.py

• src/app/api/health.py

• src/app/observability/middleware.py

• docker-compose.yml

• monitoring/docker-compose.yml