> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK https://cognite-sdk-python.readthedocs-hosted.com/en/stable/; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Industrial MCP security reference

> Technical specifications for Industrial MCP tools, permissions, authentication, data handling, and audit logging in Cognite Data Fusion (CDF).

This page explains how the Industrial MCP server works, which data and operations it exposes, and which controls you can use with your organization's security, privacy, data-classification, residency, and AI governance policies.

To connect a tool, see [Adding Industrial MCP to an AI tool](https://docs.cognite.com/cdf/build/mcp/setup.md).

## Summary

Industrial MCP is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server hosted inside Cognite Data Fusion (CDF). It lets supported MCP clients use query, time series, and document tools against the CDF industrial knowledge graph.

The Industrial MCP server uses a cluster-level endpoint:

```text theme={"languages":{"custom":["/_languages/kuiper.json"]}}
https://{cluster}.cognitedata.com/mcp
```

Existing clients can keep using the project-scoped compatibility endpoint:

```text theme={"languages":{"custom":["/_languages/kuiper.json"]}}
https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/mcp
```

Both paths reach the same Industrial MCP server and bind each connection to one project. On the cluster-level endpoint, you select the project during OAuth consent. On the compatibility endpoint, the URL names the project.

The Industrial MCP server is an alternative client protocol in front of CDF APIs. It is not a separate data store or authorization system. Every request:

* Executes under the connecting user's OpenID Connect (OIDC) identity.
* Uses the user's existing CDF group permissions.
* Is authorized against the project bound to the connection on every call.
* Produces CDF audit events.

The Industrial MCP server does not expand the data a user is authorized to access. It lets that user access the same permitted data through a supported MCP client. [Adding Industrial MCP to an AI tool](https://docs.cognite.com/cdf/build/mcp/setup.md) describes access to the industrial knowledge graph under the signed-in user's permissions.

## Tools and operations

The Industrial MCP server exposes a defined, read-only subset of the [Atlas AI tool library](https://docs.cognite.com/cdf/atlas_ai/references/atlas_ai_agent_tools.md). It is not a general-purpose remote interface and does not expose the full CDF API.

### Tool inventory

The names in this table are the tool names returned by `tools/list` on the authenticated Industrial MCP endpoint. The [Agent tools library](https://docs.cognite.com/cdf/atlas_ai/references/atlas_ai_agent_tools.md) describes the same capabilities with different names. For example, `list_instances`, `search_instances`, `aggregate_instances`, and `retrieve_instances` are operations of the [Query tool](https://docs.cognite.com/cdf/atlas_ai/references/atlas_ai_query_tool.md). `ask_document` and `summarize_document` correspond to Answer document questions and Summarize documents.

| Tool | What it does | Data returned or accessed |
| - | - | - |
| `list_views` | Lists data modeling views available to the caller. | View identifiers and metadata. |
| `get_view_schema` | Returns the schema for a selected view. | Properties, types, relations, and schema metadata. |
| `get_user_location_configuration` | Returns the caller's active location configuration. | Location and scope configuration. |
| `list_data_models` | Lists data models available to the caller. | Data model identifiers and metadata. |
| `list_instance_spaces` | Lists instance spaces available to the caller. | Space identifiers and metadata. |
| `list_instances` | Lists instances from a selected data modeling view. | Industrial records and selected properties within the caller's permissions. |
| `search_instances` | Performs free-text search within a selected view. | Matching instances and fields, including free-text fields where present. |
| `aggregate_instances` | Calculates grouped summaries and counts over a view. | Aggregate values rather than individual records. |
| `retrieve_instances` | Retrieves specific instances by space and external ID. | Requested industrial records and properties. |
| `query_time_series_datapoints` | Retrieves aggregated datapoints for 1–10 time series over a specified time range. | Aggregates such as minimum, maximum, and average. |
| `ask_document` | Answers a question using one or more CDF files as grounding material. | A model-generated answer based on relevant document content. |
| `summarize_document` | Summarizes one CDF document. | A model-generated document summary. |
| `get_file_download_url` | Creates a time-limited URL for a CDF file. | A download URL with a 30-second expiry. |

The authoritative tool list for a deployment is `tools/list` on the authenticated Industrial MCP endpoint. The response includes each tool's description and JSON Schema. Filter guidance is the MCP resource `atlas-ai://query/filter-docs`. Retrieve it with `resources/read`. It is not a callable tool.

### Operations not exposed

The Industrial MCP server does not provide the operations in the following table.

| Operation | Behavior |
| - | - |
| Access source code or files on the user's computer | The Industrial MCP server receives only tool calls sent by the MCP client and has no access to the local filesystem. |
| Execute code on the user's computer | The Industrial MCP server has no mechanism to execute local code. |
| Modify CDF data through the listed tools | The exposed operations are read-only. |
| Run arbitrary Python | Not part of the Industrial MCP tool set. |
| Call arbitrary external REST APIs | Not part of the Industrial MCP tool set. |
| Use prompts or responses to train models | Prompts and responses accessed through Cognite AI are not used to train AI models. |

## Data scope

The Industrial MCP server holds no standing credential and has no data access of its own. It cannot access anything the authenticated user could not already access through CDF. There is no MCP-specific service account, pooled credential, or separate privilege model.

The reachable data is determined by four controls that you administer:

| Control | Enforced at | Effect |
| - | - | - |
| Project selection and binding | OAuth consent and CDF authorization | The cluster-level endpoint binds the project you select during OAuth consent. The compatibility endpoint names the project in its URL. Both require authorization in that project. |
| Users permitted to complete the OAuth flow | Customer identity provider | Determines who can authenticate to the Industrial MCP endpoint. |
| CDF group capabilities and instance-space scope | CDF access management | Determines what each authenticated user can read. CDF evaluates this on every API call. |
| Selected location and data scope | CDF project configuration | By default, the Industrial MCP server uses the data scope from the user's selected location. The location configuration identifies the data models and instance spaces available to query tools. |

These controls can confine access to selected projects, locations, data models, and instance spaces. You can reuse one cluster-level configuration for projects on that cluster. Each authenticated connection is bound to one selected project. To change projects, disconnect and complete OAuth consent again. See [Access management concepts](https://docs.cognite.com/cdf/access/concepts/concepts.md), [About identity and access management](https://docs.cognite.com/cdf/access.md), and [Adding Industrial MCP to an AI tool](https://docs.cognite.com/cdf/build/mcp/setup.md).

### Enablement

When Industrial MCP is enabled for a project, you open it from the Data fusion or Atlas AI workspace. See [Adding Industrial MCP to an AI tool](https://docs.cognite.com/cdf/build/mcp/setup.md). If Industrial MCP is not available in the workspace, contact your Cognite account team.

## Architecture and data flow

The Industrial MCP server uses the signed-in user's identity and the project selected during OAuth consent to authorize calls to CDF APIs. It invokes a model endpoint only when a selected tool requires inference.

### Request flow

A user adds the Industrial MCP server in a client. The client starts an authorization code grant with Proof Key for Code Exchange (PKCE) through the Cognite identity service. The customer identity provider authenticates the user, and the user selects one CDF project. The client then sends HTTPS tool calls to the cluster-level Industrial MCP endpoint. The CDF gateway validates the token, narrows it to that project, and the Industrial MCP server calls CDF APIs as that user. Model inference runs only when the selected tool requires it. CDF writes an audit event for the API call.

```mermaid theme={"languages":{"custom":["/_languages/kuiper.json"]}}
sequenceDiagram
    participant User
    participant Client as MCP client
    participant Auth as Cognite identity service
    participant IdP as Customer identity provider
    participant Gateway as CDF gateway
    participant MCP as Industrial MCP endpoint
    participant CDF as CDF APIs
    participant Model as Model endpoint
    participant Audit as CDF audit log

    User->>Client: Add Industrial MCP configuration
    Client->>Auth: Authorization code grant with PKCE
    Auth->>IdP: Federated customer sign-in
    IdP-->>Auth: Authenticated user identity
    Auth->>User: Select one CDF project
    Auth-->>Client: Token bound to cluster and selected project
    Client->>Gateway: HTTPS request to cluster endpoint
    Gateway->>Gateway: Validate token and narrow ticket to project
    Gateway->>MCP: Forward request with authorization context
    MCP->>CDF: Execute tool call as the signed-in user
    CDF->>Audit: Write audit event
    CDF-->>MCP: Return result within user permissions
    MCP->>Model: Invoke only when the selected tool requires inference
    MCP-->>Client: Return structured tool result
    Client-->>User: Present result
```

### Responsibility boundary

Security responsibilities are shared across the customer-controlled client and identity provider, the Industrial MCP server, and the supporting CDF services.

| Boundary | Controlled by | Mechanism |
| - | - | - |
| User workstation to MCP client | Customer | Endpoint management and AI tooling policy |
| MCP client to identity provider | Customer | OIDC, conditional access, and multifactor authentication (MFA) |
| MCP client to Industrial MCP endpoint | Customer and Cognite | Transport Layer Security (TLS) and optional enterprise policy gateway |
| Industrial MCP endpoint to CDF APIs | Cognite | Authorization as the end-user principal, project isolation, and per-call capability checks |
| CDF to model endpoint | Cognite | Model endpoints available for the CDF project's cloud provider and region |
| Audit event generation | Cognite | Event generation for authenticated CDF API calls |
| Audit storage after delivery | Customer | Customer-nominated storage and customer-managed controls |

### Network path

The Industrial MCP server is served over HTTPS on the same cluster base URL as other CDF APIs. The cluster-level path is `/mcp`. The project-scoped compatibility path is `/api/v1/projects/{project}/ai/mcp`. Neither path adds a transport protocol or an inbound connection to the customer network. Existing network controls for CDF API access apply to both paths.

## Processing, storage, and logging

The following table summarizes where the Industrial MCP server processes and stores data and how CDF records activity.

| Aspect | Behavior |
| - | - |
| Endpoint execution | The Industrial MCP server runs as part of the CDF API surface in the same cluster as the CDF project. There is no separate MCP data store. |
| Data storage | Customer data remains in the CDF project's cluster storage. Backups are encrypted at rest and, on Azure, stored across at least two availability zones. See [Availability and business continuity](https://docs.cognite.com/cdf/admin/availability_continuity.md). |
| Model inference | Models available to a project depend on the cloud provider and region of that CDF project. See [Language model library](https://docs.cognite.com/cdf/atlas_ai/references/atlas_ai_agent_language_models.md) and [Clusters and regions](https://docs.cognite.com/cdf/admin/clusters_regions.md). |
| Audit event generation | Audit events are generated for authenticated CDF API activity. You can stream audit logs to storage you own. See [About CDF audit logs](https://docs.cognite.com/cdf/admin/audit/about.md). |
| Training and onward sharing | Prompts and responses accessed through Cognite AI are not used to train AI models, and customer data used by AI models is not shared with external parties. See [Trust and security](https://docs.cognite.com/cdf/trust.md). |

For dedicated clusters that are not listed on the public clusters page, confirm the cluster location, model-processing locations, and backup locations with your Cognite account team.

## Authentication and token handling

The following table summarizes the identity, authorization, and credential controls used by the Industrial MCP server.

| Aspect | Behavior |
| - | - |
| Identity provider | The OAuth flow uses the Cognite identity service, federated to the customer's identity provider. The customer identity provider authenticates the user. For the cluster-level endpoint, the consent flow asks the user to select one authorized CDF project. See [Authentication flows in CDF](https://docs.cognite.com/cdf/access/concepts/authentication_flows_oidc.md). |
| Grant type | MCP clients use the authorization code grant with PKCE. The implicit grant is not used. |
| Scope | MCP client registrations request the `IDENTITY` scope. Each host application has a separate client ID. You can grant or revoke authorization for each client in the customer identity provider. See [Access token scopes](https://docs.cognite.com/cdf/access/concepts/access_token_scopes.md). |
| Token lifetime | The customer identity-provider policy sets the access-token lifetime. |
| Cluster-level endpoint | The token audience identifies the CDF cluster, and the signed project claim identifies the selected project. CDF validates the token and issues an internal, short-lived ticket narrowed to that project. |
| Compatibility endpoint | The URL names the project, and CDF verifies that the authorization context permits it. |
| CDF ticket | Downstream CDF services authorize against the ticket. Ticket issuance is audited. See [Audit log event types reference](https://docs.cognite.com/cdf/admin/audit/event-types.md). |
| Model requests | Requests to model endpoints do not carry the customer's identity-provider credential. |

### OAuth 2.1 terminology

Cognite documents the implementation as OAuth 2.0 with OpenID Connect. OAuth 2.1 consolidates OAuth 2.0 with current security practices. It does not define a separate wire protocol. The MCP client flow uses PKCE, does not use the implicit grant, and sends bearer tokens in request headers rather than query strings.

## Gateway compatibility and audit logging

The Industrial MCP server accepts HTTPS on the cluster-level path and the project-scoped compatibility path. Its tool calls produce the same CDF audit events as other API clients.

### Gateway compatibility

The Industrial MCP server uses streamable HTTP MCP over HTTPS on the CDF cluster host:

* No non-HTTP transport is used.
* No inbound connection to the customer network is required.
* The cluster-level `/mcp` path and the project-scoped compatibility path are stable and can be allow-listed.
* Tool responses can be long-lived streams, which a proxy must support.

### Audit logging

Authenticated CDF API calls produce audit events. MCP tool calls execute through CDF APIs and follow the same audit path as other clients. Client headers in CDF audit events can identify requests from configured MCP clients. See [About CDF audit logs](https://docs.cognite.com/cdf/admin/audit/about.md).

| Dimension | Recorded information |
| - | - |
| Who | Principal ID of the user or service account. |
| When | UTC timestamp in milliseconds since epoch. |
| Which | Organization, project, service name, event type, and request parameters that identify the resources in the call. |
| Where | Caller IP address and client headers such as `x-cdp-sdk`, `x-cdp-app`, and `x-cdp-clienttag`. |

Audit log properties:

* Cognite retains audit events for 400 days.
* You can stream logs to Azure Blob Storage, Amazon S3, or Google Cloud Storage. CDF delivers them as a Delta Lake table. See [Setting up audit log streaming](https://docs.cognite.com/cdf/admin/audit/streaming.md).
* After delivery, you apply your own storage controls, such as immutability and legal hold.
* You can query delivered logs with a Delta Lake-compatible tool and forward them to a security information and event management (SIEM) system. See [Audit log query reference](https://docs.cognite.com/cdf/admin/audit/queries.md).
* Client headers can distinguish MCP-originated calls from CDF or SDK calls when the client sends those headers.
* Audit logs can contain personal data and IP addresses. Handle them as confidential data.

## Isolation and input validation

The Industrial MCP server authorizes every call as the signed-in user and validates tool arguments before it calls a CDF API.

### Isolation by user and call

The following table shows how the Industrial MCP server keeps each call within one project and one user.

| Layer | Mechanism |
| - | - |
| Project | Each connection is bound to one project, either by OAuth project selection for `/mcp` or by the project-scoped URL. Data in another project requires a separately authorized connection. See [Access management concepts](https://docs.cognite.com/cdf/access/concepts/concepts.md). |
| User | Every request is authorized as the individual OIDC principal. There is no shared MCP service account or pooled credential. |
| Session | The Industrial MCP server is stateless and retains no conversation or session state between tool calls. |
| Authorization | CDF capability checks are evaluated on every call against the target project. |

On the cluster-level endpoint, OAuth consent records the selected project in the signed token, and the CDF gateway narrows the internal ticket to that project. A missing or ambiguous project context is rejected. On the compatibility endpoint, the URL identifies the project. In both cases, CDF group membership and per-call capability checks enforce project separation.

### Session lifecycle

The Industrial MCP server maintains no long-lived server-side session. Each tool call carries its own credential and is authenticated and authorized independently. Changes to CDF group capabilities apply when authorization is evaluated on subsequent calls. Identity-provider revocation timing follows the access-token lifetime configured in the customer identity provider.

### JSON Schema validation

The MCP `tools/list` response includes a JSON Schema `inputSchema` for each tool. The Industrial MCP server validates arguments against the schema before execution. Invalid arguments return a tool error and are not passed to the underlying CDF API. Tool results are returned as structured JSON.

## Tool manifest

The authenticated `tools/list` response provides the live tool manifest, including tool names, descriptions, and JSON Schemas.

* The manifest is retrieved directly from the deployment over authenticated TLS.
* TLS provides transport integrity and server authentication.
* You can retain a hash of the response and compare it with later responses if your change-management process requires change detection.

Cognite does not publish a detached cryptographic signature for the tool manifest. Contact your Cognite account team if a detached signature is a policy requirement.

## Platform controls and telemetry

Cognite applies the same platform controls to the Industrial MCP server as to other CDF APIs, and records operational and audit telemetry for those calls.

### Platform controls

The following table lists the platform controls that apply to the Industrial MCP server.

| Control | Implementation |
| - | - |
| Transport encryption | CDF API traffic, including the Industrial MCP server, is served over HTTPS. |
| Infrastructure hardening | Governed by Cognite platform engineering standards and covered by Cognite's independently audited control environment. |
| Secret management | Cognite platform services use managed secret storage. |
| Development security gates | Cognite's development lifecycle includes static analysis, automated dependency updates, mandatory review, and required status checks. |
| Vulnerability disclosure | Cognite publishes a [vulnerability disclosure policy](https://docs.cognite.com/cdf/trust/vulnerability-disclosure-policy.md). |
| Certifications and reports | Current certifications, audit reports, and penetration-test material are available through the [Cognite Trust Center](https://trust.cognite.com/). |

See [Trust and security](https://docs.cognite.com/cdf/trust.md) and [Shared security responsibility](https://docs.cognite.com/cdf/trust/security/security_intro.md#shared-security-responsibility).

### Telemetry

The following table identifies the telemetry generated by the Industrial MCP server and its retention basis.

| Data | Recorded | Retention | Purpose and notes |
| - | - | - | - |
| CDF API audit events | Yes | 400 days | Security, compliance, and incident investigation. Can include personal data and IP addresses. |
| Authentication events | Yes | Audit retention | Authentication traceability for documented OIDC claims. |
| Credential exchange events | Yes | Audit retention | Traceability of token-to-ticket exchange. Query strings are excluded from logged paths. |
| AI token-consumption metering | Yes | Per metering API | Aggregate licensing, capacity, and cost-management counts. Not prompt content. |
| Platform operational logs and metrics | Yes | Per platform policy | Availability and performance, governed by Cognite's audited control environment. |
| Prompt and response content used to train models | No | None | Cognite AI does not use prompts and responses to train models. |
| Customer data shared with external parties | No | None | Cognite AI data-handling commitment. See [Trust and security](https://docs.cognite.com/cdf/trust.md). |
| Source code or local filesystem content | No | None | The Industrial MCP server has no access to the user's computer. |

## Ongoing review

Use the following mechanisms to review the Industrial MCP tool surface and related security controls.

| Review need | Available mechanism |
| - | - |
| Current tool surface | Retrieve `tools/list` from the Industrial MCP endpoint and compare it with a retained baseline if your process requires change detection. |
| Product and feature changes | Review [What's new?](https://docs.cognite.com/cdf/whatsnew.md) for feature-status changes, deprecations, and retirements. |
| Certification and control status | Review current reports in the [Cognite Trust Center](https://trust.cognite.com/). |
| Vulnerability reporting | Use the [vulnerability disclosure policy](https://docs.cognite.com/cdf/trust/vulnerability-disclosure-policy.md). |
| Incident notification | Governed by the applicable Cognite agreement. |
| Changes affecting a dedicated cluster | Coordinate with the Cognite account team. |

Define review cadence, advance-notice commitments, and notification obligations according to your policy and the applicable Cognite agreement.

## Technical reference

The following table lists the endpoint, transport, and authentication values used by Industrial MCP clients.

| Item | Value |
| - | - |
| Cluster-level endpoint | `https://{cluster}.cognitedata.com/mcp` |
| Project-scoped compatibility endpoint | `https://{cluster}.cognitedata.com/api/v1/projects/{project}/ai/mcp` |
| Transport | Streamable HTTP MCP over HTTPS |
| Example server name | `cognite` |
| Cursor OAuth client ID | `industrial-mcp-cursor` |
| Claude Code OAuth client ID | `industrial-mcp-claude` |
| GitHub Copilot OAuth client ID | `industrial-mcp-copilot` |
| Programmatic client OAuth client ID | `industrial-mcp-client` |
| OAuth scope | `IDENTITY` |
| Claude Code OAuth callback port | `3118` (loopback) |
| Grant type | Authorization code with PKCE |
| Audit log retention at Cognite | 400 days |

A client configuration names the server `cognite` and sets its URL to the cluster-level Industrial MCP endpoint. Replace `{cluster}` with the CDF cluster. You select the project during sign-in.

```json wrap theme={"languages":{"custom":["/_languages/kuiper.json"]}}
{
  "mcpServers": {
    "cognite": {
      "url": "https://{cluster}.cognitedata.com/mcp"
    }
  }
}
```