AI tools

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools. The Oceanum Datamesh MCP server exposes the Datamesh as a set of MCP tools, so an assistant such as Claude — or a coding agent in your IDE — can search the catalogue, inspect datasources and pull data directly into your conversation or workspace.

The server is the oceanum-mcp package. It authenticates with the same Datamesh token and talks to the same Datamesh APIs as every other integration.

What the assistant can do

The Datamesh MCP server provides these tools:

search_catalog — discover datasources across the catalogue.
get_datasource_info — inspect a datasource’s schema, variables and coverage.
stage_query — a dry run that reports the result size without downloading anything.
query_data — run a query and return small results inline.
load_datasource — load a datasource for further processing.
export_query — export a full result that is too large to return inline: a download link on the hosted server, or a local file on the local server (see below).
update_metadata — a write tool for editing datasource metadata (disabled in read-only mode).

The intended workflow is search_catalog → get_datasource_info → stage_query → then query_data for small, inline results, or export_query for large results (a download link on the hosted server, or a local file on the local server). Always stage a query before pulling data, and narrow large results with time, geographic and variable filters.

Two ways to connect

There are two ways to reach the Datamesh MCP server. Most tools support at least one of them.

Hosted (remote) server — no install

A streamable-HTTP endpoint that requires nothing to install:

https://mcp.oceanum.io/datamesh

The hosted server runs read-only and multi-tenant: every request executes as the calling user, and connections are never shared between credentials.

query_data returns results inline, in the conversation, which is capped at roughly 50 MB — above that, gridded queries come back as structure-only summaries (no values) and tabular queries are refused. So large results can’t be returned in the conversation, but you can still export them: the export_query tool returns a time-limited download link to the full result, which you fetch out-of-band (see Working with large data). Being read-only, the hosted server disables the write tools (update_metadata and storage writes).

Authenticate in one of two ways:

OAuth (sign in with Oceanum.io) — used by Claude’s custom connectors. You add a connector pointing at the endpoint, click Connect and log in with your Oceanum.io account.
Header token — send your Datamesh token as a custom X-DATAMESH-TOKEN HTTP header. This is the universal remote path for any client that supports remote MCP servers with custom headers, and avoids OAuth setup entirely.

Local (stdio) server — full-featured

Run the server locally over stdio with uvx (no install) or from a pip install:

uvx oceanum-mcp datamesh

Authenticate with the DATAMESH_TOKEN environment variable. The local server is full read/write, including export_query to local files, and works with any client that supports stdio MCP servers.

Which should I use?

Hosted is zero-install and read-only. It returns small results inline and, for large results, export_query hands back a download link — a great fit for exploratory chat and for pulling data without installing anything.
Local gives full read/write and writes export_query output straight to a file on your machine — the right choice for coding agents and pipelines that consume the file directly.

Working with large data

query_data returns results inline, so it is capped at roughly 50 MB — above that, gridded queries return structure-only summaries and tabular queries are refused. For results too large to return inline, use export_query, which never puts the data in the conversation. It works on both servers, differing only in where the full result lands:

Hosted: export_query returns a time-limited, self-authenticating download link to the full result (choose netcdf, parquet or csv). Fetch it out-of-band — with curl or your own code, no credentials required. The link carries its own signature, so treat it like a password. Nothing to install.
Local: export_query writes the full result to a file on your machine (NetCDF for gridded data, Parquet or CSV for tabular), which your analysis code reads directly. This needs the local server (below).

A typical large-data workflow is stage_query (check the size) → export_query (download link or file) → analyse the result in your own code.

Running the local server

For the file-writing export path — and for full read/write access — run the MCP server locally with uv (nothing to install) or a pip install:

# Run directly with uvx — nothing to install
uvx oceanum-mcp datamesh

# ...or install into your environment
pip install oceanum-mcp

Set your Datamesh token in the environment:

export DATAMESH_TOKEN="your-token-here"

Then point your AI tool at the local (stdio) server — see the per-tool pages below.

Connect your tool

Claude

Claude.ai, Claude Desktop and Claude Code

Cursor

Remote header or local stdio server

VS Code

GitHub Copilot agent mode

Windsurf

Cascade MCP integration

Cline

Remote or local MCP servers

Continue

MCP servers in config.yaml

ChatGPT

Remote Developer Mode connector

OpenAI Codex

CLI agent — remote header or local stdio

Other MCP clients

The general remote and local pattern

Keep your token safe

Your Datamesh token belongs to your organisation and grants access to all of its permissioned datasources — including the ability to modify or delete them. Treat it as a secret, never paste it into a shared chat, and prefer the hosted read-only server for exploratory AI use.