# ibm/ibm-openpages-mcp-server architecture

> Architecture diagram of the GitHub repository ibm/ibm-openpages-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibm/ibm-openpages-mcp-server
- Repository: https://github.com/ibm/ibm-openpages-mcp-server

## Overview

#### 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`

Main entry points: [`src/app/mcp/remote/http_router.py`](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/remote/http_router.py) (HTTP MCP router), [`src/app/mcp/request_processor.py`](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/request_processor.py) (Request processor), [`src/app/mcp/schema_builder.py`](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/schema_builder.py) (Schema builder), [`src/app/tools/generic_object_tools.py`](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/tools/generic_object_tools.py) (Generic object tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & Transport"]
  node_entry["Runtime entry<br/>Python entrypoint<br/>[main.py]"]
  node_local_runner["Local stdio runner<br/>MCP transport<br/>[runner.py]"]
  node_remote_server["Remote server assembly<br/>HTTP runtime<br/>[server_instance.py]"]
  node_http_router["HTTP MCP router<br/>JSON-RPC endpoint<br/>[http_router.py]"]
  node_mcp_server["MCP server<br/>protocol facade<br/>[mcp_server.py]"]
  node_request_processor["Request processor<br/>MCP dispatcher"]
end

subgraph group_capabilities["Capabilities"]
  node_settings["Settings &amp; object catalog<br/>deployment policy<br/>[settings.py]"]
  node_object_catalog["Object-type catalog<br/>capability catalog<br/>[object_types.json]"]
  node_schema_builder["Schema builder<br/>metadata formatter<br/>[schema_builder.py]"]
  node_tool_handlers["Tool handlers<br/>MCP tools<br/>[tool_handlers.py]"]
  node_generic_tools["Generic object tools<br/>tool definitions"]
  node_query_tool["Query tool<br/>query execution<br/>[query_tool.py]"]
  node_resources["Schema resources<br/>MCP resources"]
  node_prompts["Agent usage prompt<br/>MCP prompts<br/>[prompt_handlers.py]"]
end

subgraph group_integration["OpenPages Integration"]
  node_openpages_client{{"OpenPages client<br/>external API client"}}
end

subgraph group_auth["Authentication"]
  node_auth_service["Authentication service<br/>credential resolver<br/>[service.py]"]
  node_request_context["Request context<br/>identity metadata<br/>[context.py]"]
end

subgraph group_operations["Operations"]
  node_schema_cache[("Schema cache manager<br/>metadata cache")]
  node_rabbitmq["RabbitMQ synchronization<br/>cache invalidation<br/>[rabbitmq_client.py]"]
  node_health["Health &amp; metrics<br/>operations endpoints<br/>[health.py]"]
  node_observability["Observability middleware<br/>telemetry<br/>[middleware.py]"]
end

node_entry -->|"local mode"| node_local_runner
node_entry -->|"remote mode"| node_remote_server
node_remote_server -->|"mounts"| node_http_router
node_local_runner -->|"stdio"| node_mcp_server
node_http_router -->|"JSON-RPC"| node_mcp_server
node_mcp_server -->|"dispatches"| node_request_processor
node_request_processor -->|"tool calls"| node_tool_handlers
node_request_processor -->|"resource calls"| node_resources
node_request_processor -->|"prompt calls"| node_prompts
node_settings -->|"loads"| node_object_catalog
node_object_catalog -->|"filters metadata"| node_schema_builder
node_settings -->|"selects tool mode"| node_generic_tools
node_schema_builder -->|"validates schemas"| node_generic_tools
node_tool_handlers -->|"object operations"| node_generic_tools
node_tool_handlers -->|"queries"| node_query_tool
node_generic_tools -->|"CRUD &amp; associations"| node_openpages_client
node_query_tool -->|"executes query"| node_openpages_client
node_resources -->|"publishes schemas"| node_schema_builder
node_schema_builder -->|"caches metadata"| node_schema_cache
node_rabbitmq -->|"invalidates"| node_schema_cache
node_http_router -->|"authenticates"| node_auth_service
node_auth_service -->|"establishes identity"| node_request_context
node_auth_service -->|"supplies credentials"| node_openpages_client
node_remote_server -->|"exposes operations"| node_health
node_http_router -->|"instruments"| node_observability

click node_entry "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/main.py"
click node_local_runner "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/local/runner.py"
click node_remote_server "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/remote/server_instance.py"
click node_http_router "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/remote/http_router.py"
click node_mcp_server "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/mcp_server.py"
click node_request_processor "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/request_processor.py"
click node_settings "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/config/settings.py"
click node_object_catalog "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/config/object_types.json"
click node_schema_builder "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/schema_builder.py"
click node_tool_handlers "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/tool_handlers.py"
click node_generic_tools "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/tools/generic_object_tools.py"
click node_query_tool "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/tools/query_tool.py"
click node_resources "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/resource_handlers.py"
click node_prompts "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/prompt_handlers.py"
click node_auth_service "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/auth/service.py"
click node_request_context "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/context.py"
click node_openpages_client "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/core/openpages_client.py"
click node_schema_cache "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/cache/schema_cache_manager.py"
click node_rabbitmq "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/cache/rabbitmq_client.py"
click node_health "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/api/health.py"
click node_observability "https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/observability/middleware.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_local_runner,node_remote_server,node_http_router,node_mcp_server,node_request_processor toneBlue
class node_settings,node_object_catalog,node_schema_builder,node_tool_handlers,node_generic_tools,node_query_tool,node_resources,node_prompts toneAmber
class node_openpages_client toneMint
class node_auth_service,node_request_context toneRose
class node_schema_cache,node_rabbitmq,node_health,node_observability toneIndigo
```

## Components

### Runtime & Transport

- [Runtime entry](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/main.py): Python entrypoint · Selects local stdio or remote HTTP mode. · `main.py`
- [Local stdio runner](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/local/runner.py): MCP transport · `src/app/mcp/local/runner.py`
- [Remote server assembly](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/remote/server_instance.py): HTTP runtime · `src/app/mcp/remote/server_instance.py`
- [HTTP MCP router](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/remote/http_router.py): JSON-RPC endpoint · Serves remote clients at /mcp. · `src/app/mcp/remote/http_router.py`
- [MCP server](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/mcp_server.py): protocol facade · `src/app/mcp/mcp_server.py`
- [Request processor](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/request_processor.py): MCP dispatcher · Normalizes requests and routes methods. · `src/app/mcp/request_processor.py`

### Capabilities

- [Settings & object catalog](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/config/settings.py): deployment policy · Environment settings and configured object types define exposed capabilities. · `src/app/config/settings.py`
- [Object-type catalog](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/config/object_types.json): capability catalog · `src/app/config/object_types.json`
- [Schema builder](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/schema_builder.py): metadata formatter · Filters OpenPages metadata into agent-visible schemas. · `src/app/mcp/schema_builder.py`
- [Tool handlers](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/tool_handlers.py): MCP tools · Routes CRUD, association, lookup, and query calls. · `src/app/mcp/tool_handlers.py`
- [Generic object tools](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/tools/generic_object_tools.py): tool definitions · Generates ontology-based and per-type tools. · `src/app/tools/generic_object_tools.py`
- [Query tool](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/tools/query_tool.py): query execution · Executes OpenPages SQL-like queries. · `src/app/tools/query_tool.py`
- [Schema resources](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/resource_handlers.py): MCP resources · Publishes catalog, schemas, grammar, and fallback tools. · `src/app/mcp/resource_handlers.py`
- [Agent usage prompt](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/prompt_handlers.py): MCP prompts · `src/app/mcp/prompt_handlers.py`

### OpenPages Integration

- [OpenPages client](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/core/openpages_client.py): external API client · REST/API boundary to the configured OpenPages instance. · `src/app/core/openpages_client.py`

### Authentication

- [Authentication service](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/auth/service.py): credential resolver · Resolves server or per-user credentials without unsafe fallback. · `src/app/auth/service.py`
- [Request context](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/mcp/context.py): identity metadata · Carries user and view metadata into request boundaries. · `src/app/mcp/context.py`

### Operations

- [Schema cache manager](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/cache/schema_cache_manager.py): metadata cache · `src/app/cache/schema_cache_manager.py`
- [RabbitMQ synchronization](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/cache/rabbitmq_client.py): cache invalidation · Refreshes cached schema metadata. · `src/app/cache/rabbitmq_client.py`
- [Health & metrics](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/api/health.py): operations endpoints · Provides health checks, cache statistics, and optional metrics. · `src/app/api/health.py`
- [Observability middleware](https://github.com/ibm/ibm-openpages-mcp-server/blob/develop/src/app/observability/middleware.py): telemetry · Instruments requests with logs, traces, and metrics. · `src/app/observability/middleware.py`

## Connections

- Runtime entry → Local stdio runner: local mode
- Runtime entry → Remote server assembly: remote mode
- Remote server assembly → HTTP MCP router: mounts
- Local stdio runner → MCP server: stdio
- HTTP MCP router → MCP server: JSON-RPC
- MCP server → Request processor: dispatches
- Request processor → Tool handlers: tool calls
- Request processor → Schema resources: resource calls
- Request processor → Agent usage prompt: prompt calls
- Settings & object catalog → Object-type catalog: loads
- Object-type catalog → Schema builder: filters metadata
- Settings & object catalog → Generic object tools: selects tool mode
- Schema builder → Generic object tools: validates schemas
- Tool handlers → Generic object tools: object operations
- Tool handlers → Query tool: queries
- Generic object tools → OpenPages client: CRUD & associations
- Query tool → OpenPages client: executes query
- Schema resources → Schema builder: publishes schemas
- Schema builder → Schema cache manager: caches metadata
- RabbitMQ synchronization → Schema cache manager: invalidates
- HTTP MCP router → Authentication service: authenticates
- Authentication service → Request context: establishes identity
- Authentication service → OpenPages client: supplies credentials
- Remote server assembly → Health & metrics: exposes operations
- HTTP MCP router → Observability middleware: instruments