# ITWorx MCP Hub integration

## Objective

Publish four read-only MobilityOps capabilities through the existing central ITWorx MCP Hub. MobilityOps does not host MCP transport itself.

## Provider registration

- provider ID: `mobilityops` (registered on the Hub side; the Hub's own registration is
  catalog-driven — it reconciles its catalog into the gateway, Fleet Ops never pushes a
  registration call)
- API base: internal Fleet Ops API URL, reached via `MCP_HUB_SERVICE_TOKEN` auth
- authentication: scoped service token (`X-Service-Token`), plus `X-Client-Id`
- mode: read-only
- **Confirmed live in production** on the ITWorx MCP Hub's own deployment (Tower), with
  a real contract fix already applied there (`vehicle.get`'s wire parameter normalized to
  camelCase `vehicleRef`). `docs/final-integrations/current-state-audit.md` has the full
  evidence.

## Tools

The machine-readable definitions are in `contracts/mcp-tools.json`. The Hub's own live
connector (`ITWorx_MCP_Hub` repo, `connectors/mobilityops/`) publishes these under its
own dotted namespace — that naming is the Hub's to own, not Fleet Ops's:

1. `mobilityops.operations.summary`
2. `mobilityops.attention.list`
3. `mobilityops.vehicle.get`
4. `mobilityops.knowledge.search`

Fleet Ops's own internal audit trail (`AuditEvent.metadata_json.tool`, visible on
`/api/v1/audit?action=mcp_tool_request`) labels these calls `fleet_ops_get_operations_summary`,
`fleet_ops_list_attention_vehicles`, `fleet_ops_get_vehicle_details`,
`fleet_ops_search_knowledge` — a separate, Fleet-Ops-owned naming layer for its own audit
log, not the wire-level MCP tool name a client calls.

`search-knowledge` accepts a `locale` field (`nl-BE` | `en-GB` | `fr-BE`, default
`en-GB`) that is passed straight through to the active knowledge provider.

## Correlation ID

The inbound `X-Correlation-Id` header (set by the Hub, itself either forwarding the
MCP client's ID or minting one) is preserved through Fleet Ops's own handling and audit
log; Fleet Ops only mints a fresh correlation ID when none is supplied or the supplied
value isn't a valid UUID. See `get_correlation_id` in
`backend/app/api/routers/mcp_integrations.py`.

## Routing

Operational tools:

```text
AI client -> MCP Hub -> MobilityOps provider API
```

Knowledge tool:

Preferred:

```text
AI client -> MCP Hub -> RAGcore workspace mobilityops
```

If the Hub requires a single provider boundary, route through a narrow MobilityOps knowledge façade that calls RAGcore. Do not duplicate retrieval logic.

## Restrictions

Do not expose:

- generic SQL;
- arbitrary URL fetching;
- arbitrary shell commands;
- return registration;
- customer merge;
- booking or vehicle mutation;
- secrets or raw service configuration.

## Audit

The Hub owns central tool-call audit. MobilityOps also records service requests that reach its provider APIs with tool name, correlation ID, client/service identity and result status.