cog-mcp-experimental 0.2.8

Unofficial MCP server for Cognite Data Fusion data modeling

cog-mcp-experimental

MCP server for Cognite Data Fusion data modeling. Exposes data model schemas as resources, instance operations (list, search, query, aggregate, retrieve), and AI document tools (question answering and summarization).

Quick start

uvx cog-mcp-experimental

Configuration

Configuration is via environment variables — either passed through your MCP client's config, or loaded from a .env file in the working directory.

Using a .env file

Create a .env file (and add it to .gitignore):

CDF_CLIENT_ID=your-client-id
CDF_TENANT_ID=your-tenant-id
CDF_CLUSTER=westeurope-1
CDF_PROJECT=your-project
CDF_CLIENT_SECRET=your-secret
CDF_DATA_MODELS=[{"space": "mySpace", "externalId": "MyModel", "version": "1"}]
CDF_INSTANCE_SPACES=["instanceSpace1"]

The .env file does not override existing environment variables — explicit env vars from your MCP client config or shell always take precedence.

Required environment variables

Variable	Description
CDF_CLIENT_ID	OAuth client ID
CDF_TENANT_ID	Azure AD tenant ID
CDF_CLUSTER	CDF cluster (e.g. westeurope-1)
CDF_PROJECT	CDF project name
CDF_CLIENT_SECRET	OAuth client secret
CDF_DATA_MODELS	JSON array of data models: [{"space": "s", "externalId": "m", "version": "1"}]
CDF_INSTANCE_SPACES	JSON array of space IDs for automatic instance filtering: ["space1"]

Optional

Variable	Description
CDF_TOKEN_URL	Override OAuth token URL (defaults to Azure AD)

Client setup

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cog-mcp-experimental": {
      "command": "uvx",
      "args": ["cog-mcp-experimental"],
      "env": {
        "CDF_CLIENT_ID": "your-client-id",
        "CDF_TENANT_ID": "your-tenant-id",
        "CDF_CLUSTER": "westeurope-1",
        "CDF_PROJECT": "your-project",
        "CDF_CLIENT_SECRET": "your-secret",
        "CDF_DATA_MODELS": "[{\"space\": \"mySpace\", \"externalId\": \"MyModel\", \"version\": \"1\"}]",
        "CDF_INSTANCE_SPACES": "[\"instanceSpace1\"]"
      }
    }
  }
}

Cursor

.cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cog-mcp-experimental": {
      "command": "uvx",
      "args": ["cog-mcp-experimental"],
      "env": {
        "CDF_CLIENT_ID": "your-client-id",
        "CDF_TENANT_ID": "your-tenant-id",
        "CDF_CLUSTER": "westeurope-1",
        "CDF_PROJECT": "your-project",
        "CDF_CLIENT_SECRET": "${env:CDF_CLIENT_SECRET}",
        "CDF_DATA_MODELS": "[{\"space\": \"mySpace\", \"externalId\": \"MyModel\", \"version\": \"1\"}]",
        "CDF_INSTANCE_SPACES": "[\"instanceSpace1\"]"
      }
    }
  }
}

Claude Code

claude mcp add --transport stdio \
  --env CDF_CLIENT_ID=your-client-id \
  --env CDF_TENANT_ID=your-tenant-id \
  --env CDF_CLUSTER=westeurope-1 \
  --env CDF_PROJECT=your-project \
  --env 'CDF_DATA_MODELS=[{"space":"mySpace","externalId":"MyModel","version":"1"}]' \
  --env 'CDF_INSTANCE_SPACES=["instanceSpace1"]' \
  cog-mcp-experimental -- uvx cog-mcp-experimental

CDF_CLIENT_SECRET is inherited from your shell environment.

Tools

Discovery

Tool	Description
list_views	List available views with their space, externalId, and version
get_view_schema	Get full property schema for a view (names, types, relations)
get_filter_docs	Reference documentation for filter syntax
get_query_docs	Reference documentation for graph query syntax

Instance operations

Tool	Description
list_instances	List/filter instances of a view with pagination
search_instances	Full-text search across instances
aggregate_instances	Count, sum, avg, min, max, histogram
query_instances	Graph query across related instances
retrieve_instances	Get specific instances by ID

All instance tools automatically apply space filters from CDF_INSTANCE_SPACES.

AI document tools

Tool	Description
ask_documents_question	Ask questions about PDF documents using document instanceId values
summarize_document	Summarize a single PDF document using document instanceId

Resources

The same discovery information is also available as MCP resources for clients that support them:

URI	Description
cdf://views	List all available views
cdf://views/{space}/{externalId}/{version}	View schema with property details
cdf://docs/filters	Filter syntax reference
cdf://docs/querying	Query syntax reference

Development

git clone <repo>
cd cog-mcp-experimental
uv sync --dev       # install project + dev dependencies
uv run cog-mcp-experimental  # start the MCP server locally

Common commands

Command	Description
uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/ && uv run pytest	Lint + tests (same gate as CI)
uv run pytest	Run test suite with coverage
uv run ruff check src/ tests/	Check for lint issues
uv run ruff check --fix src/ tests/ && uv run ruff format src/ tests/	Auto-fix lint + reformat
uv run pytest -k "<expression>"	Run a subset of tests

Testing with MCP Inspector

npx @modelcontextprotocol/inspector