Oceanum MCP
OfficialOceanum MCP gives AI assistants tools to discover, inspect, query, export, and update ocean/environmental datasets, plus manage files in Oceanum cloud storage.
Search the Datamesh catalog by text, time range, and bounding box.
Fetch datasource metadata, coverage, coordinates, and variables.
Dry-run queries to estimate result size without downloading data.
Query datasources inline with filters, spatial/temporal selection, resampling, aggregation, and record limits.
Export full query results to NetCDF, Parquet, or CSV, or get a hosted download URL.
Summarize entire datasources lazily or download small tabular ones.
Update datasource metadata such as name, description, tags, labels, and details when not read-only.
List storage files recursively, check existence, read/write text files, delete files/directories, and inspect file metadata.
Supports optional Auth0 JWT authentication for the hosted HTTP transport, validating bearer tokens against a configurable Auth0 tenant domain and API audience.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Oceanum MCP search for sea surface temperature datasets in the North Atlantic"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Oceanum MCP
An MCP server package that provides AI assistants with access to the Oceanum platform for ocean/environmental data and cloud storage.
Servers
This package contains multiple MCP servers, selectable at runtime:
Server | Description |
| Search, query, and manage ocean/environmental datasets |
| List, read, write, and delete files in Oceanum cloud storage |
| All tools from both servers under a single endpoint (default) |
Related MCP server: Code Ocean MCP Server
Prerequisites
Get an API token from oceanum.io. Set it as the DATAMESH_TOKEN environment variable
(or keep it out of the client config: see Supplying the token without
putting it in the client config).
Installation
Requires Python 3.10–3.13. Python 3.14 is not supported yet: the zarr 2.x
stack that oceanum depends on needs numcodecs<0.16, which has no Python
3.14 wheels.
pip install oceanum-mcpOr run directly with uvx. Pass --python 3.13 so uv doesn't pick Python
3.14 (uv downloads 3.13 if it isn't installed):
uvx --python 3.13 oceanum-mcp # combined server (default)
uvx --python 3.13 oceanum-mcp datamesh # datamesh only
uvx --python 3.13 oceanum-mcp storage # storage only
uvx --python 3.13 oceanum-mcp --list # show available serversConfiguration
Claude Desktop
Add to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Combined server (all tools):
{
"mcpServers": {
"oceanum": {
"command": "uvx",
"args": ["--python", "3.13", "oceanum-mcp"],
"env": {
"DATAMESH_TOKEN": "your-token-here"
}
}
}
}Individual server (datamesh only):
{
"mcpServers": {
"oceanum-datamesh": {
"command": "uvx",
"args": ["--python", "3.13", "oceanum-mcp", "datamesh"],
"env": {
"DATAMESH_TOKEN": "your-token-here"
}
}
}
}Claude Code
# Combined server
claude mcp add --transport stdio oceanum -- uvx --python 3.13 oceanum-mcp
# Individual server
claude mcp add --transport stdio oceanum-datamesh -- uvx --python 3.13 oceanum-mcp datameshSet the token in your environment:
export DATAMESH_TOKEN=your-token-hereVS Code / Cline / Continue
Use stdio transport with the same command:
{
"command": "uvx",
"args": ["--python", "3.13", "oceanum-mcp"],
"env": {
"DATAMESH_TOKEN": "your-token-here"
}
}If the server reports that the token "looks like an unresolved client
variable", your client passed a config variable such as
${input:datamesh-token} through literally instead of substituting it.
Restart the server from the client so it prompts for the input again, or use
one of the options below.
Supplying the token without putting it in the client config
For the stdio transport the server takes its token from the first of these that is set:
DATAMESH_TOKEN— the token itself.DATAMESH_TOKEN_FILE— path to a file containing the token (~is expanded). On macOS/Linux the file must be accessible only by you; the server refuses it otherwise:install -m 600 /dev/null ~/.config/oceanum/token echo "your-token-here" > ~/.config/oceanum/token"env": { "DATAMESH_TOKEN_FILE": "~/.config/oceanum/token" }The file is read on every call, so a replaced token takes effect without restarting the server.
DATAMESH_TOKEN_KEYRING=1— read the token from the OS credential store (macOS Keychain, Secret Service/libsecret on Linux, Windows Credential Manager) via thekeyringpackage, under serviceoceanum-mcp, userdatamesh-token. Store it once with:uvx keyring set oceanum-mcp datamesh-tokenThe token is looked up once per server process, so restart the server after changing it.
keyringcurrently arrives as an indirect dependency offastmcp, which is not guaranteed to last: to be sure, install theoceanum-mcp[keyring]extra (with uvx:uvx --python 3.13 --from "oceanum-mcp[keyring]" oceanum-mcp).
Troubleshooting: -32022 on the first initialize
A client may log "connection is serving the 2026-07-28 protocol; the
initialize handshake is not accepted" (error -32022) once on connect. This
comes from the MCP Python SDK, not from this server's code: in SDK 2.3.0
(mcp/server/runner.py, serve_dual_era_loop) a connection's first request
fixes its protocol era. A client that opens with a 2026-07-28 request and
then sends the older initialize handshake on the same connection is
refused, with the supported versions in the error. Clients are expected to
retry with a supported version; GitHub Copilot did so and connected.
Environment Variables
Variable | Required | Description |
| Yes* | Oceanum API token (shared by all servers) |
| Yes* | Path to a file holding the token, readable only by its owner; used when |
| Yes* |
|
| No | Custom datamesh service URL (default: |
| No | Custom storage service URL (default: |
| No | Override the base domain for all services (default: |
| No | Admin service URL, which serves datasource notices; must be an |
| No |
|
| No |
|
| No | Max staged result size returned inline by |
| No | Max rows/records previewed inline before truncation (default 100) |
| No | If set, |
| No | Seconds a Datamesh staging/query request may wait on the gateway before the tool returns a timeout error (default 120) |
| No | Auth scheme for |
| No | Auth0 tenant domain for |
| No | Auth0 API audience for |
| No | Externally visible base URL (e.g. |
| No | Comma-separated browser origins allowed by CORS on http (default: |
* One token source (DATAMESH_TOKEN, DATAMESH_TOKEN_FILE or
DATAMESH_TOKEN_KEYRING) is required for the stdio transport (and for
--transport http with OCEANUM_MCP_AUTH=none); in authenticated http mode
each request carries its own credential and no server-side token is needed.
Hosted mode (HTTP transport)
Run any server as a shared, multi-tenant HTTP service:
oceanum-mcp datamesh --transport http --host 0.0.0.0 --port 8000This serves the MCP streamable-HTTP endpoint at http://<host>:<port>/<server>
(/datamesh here; override with --path). Each server owning its own path
lets several MCP servers share one domain behind an ingress — e.g.
https://mcp.oceanum.io/datamesh and https://mcp.oceanum.io/storage.
Every request must present a bearer credential, and all Datamesh/Storage calls
are made as that request's user — connections are cached per credential and
never shared between tokens.
Auth schemes (OCEANUM_MCP_AUTH):
auto(default) — accepts either credential, detected per request: Datamesh tokens arrive in theX-DATAMESH-TOKENheader (the same header the gateway itself uses), Auth0 JWTs inAuthorization: Bearer. A Datamesh token sent as the bearer also works (JWT-shape detection routes it), but the dedicated header is the canonical form. Each request runs as the identity its own credential resolves to.datamesh— only Datamesh tokens are accepted. The server validates them against the gateway. Add to Claude Code with:claude mcp add --transport http oceanum-datamesh https://mcp.oceanum.io/datamesh \ --header "X-DATAMESH-TOKEN: <datamesh-token>"auth0— clients send an Auth0-issued JWT, validated against the tenant JWKS and forwarded to the Datamesh gateway as-is.none— no authentication; every request uses the server's ownDATAMESH_TOKEN. Only for trusted-network deployments.
Notes:
export_queryworks over HTTP but changes shape: instead of writing to the server's local filesystem (meaningless for remote clients), it returns a time-limited, self-authenticating gatewaydownload_urlthat the caller fetches out-of-band. Thepathargument is ignored on hosted servers. The URL needs no credential, so it is a capability — treat it as a secret. Gateways with scoped download links (OCE-317) also limit its lifetime and number of fetches; the response then reports them asexpires_atandmax_uses. Hosted exports are capped at 10 GB to bound what one link can pull, and exports above 1 GB needconfirm_size_bytes(seeexport_query).A rejected Datamesh token (in
X-DATAMESH-TOKEN, or a non-JWTAuthorization: Bearer) gets a 401 saying the token was not accepted, without the OAuthresource_metadatachallenge (which would send clients such as VS Code into a sign-in flow that cannot fix a Datamesh token). Requests with no credential, and failed JWT (OAuth) bearers, still get the challenge, so OAuth discovery and re-authorization are unaffected. If the token could not be verified because the Datamesh service was unreachable, the response is a 503 asking to retry instead. A credential that is an unsubstituted client variable (${input:...}) gets a 401 saying so (except withOCEANUM_MCP_AUTH=none, where client credentials are ignored).Combine with
OCEANUM_MCP_READ_ONLY=1to run a read-only public service.Pass
--statelesswhen running behind a load balancer or on autoscaled platforms (Cloud Run, etc.): sessions are otherwise held in instance memory, and consecutive requests routed to different instances would fail.Breaking change for
--transport sse(deprecated): sse is a network transport and now behaves like http — authenticated by default and noexport_query. SetOCEANUM_MCP_AUTH=noneto restore the old unauthenticated behavior.
Serving under an external ASGI server
To run under uvicorn/gunicorn (multiple workers, serverless platforms), use
the packaged app factory — it applies the same auth and tool policy as the
CLI; serving mcp.http_app() directly would bypass both:
uvicorn --factory oceanum_mcp.app:create_http_app --host 0.0.0.0 --port 8000Requests on a network transport never fall back to the server's
DATAMESH_TOKEN: an unauthenticated request fails unless
OCEANUM_MCP_AUTH=none was set explicitly.
Browser clients (CORS)
Browser-based MCP clients send a CORS preflight (OPTIONS) before every
cross-origin request. The http app answers preflights for an allowlist of
origins, ahead of authentication (a preflight never carries a credential);
all other requests still require one. Configure the allowlist with
OCEANUM_MCP_CORS_ORIGINS, comma-separated:
OCEANUM_MCP_CORS_ORIGINS="https://*.oceanum.io,https://vscode.dev,http://localhost:6274"Unset:
https://*.oceanum.io,https://*.oceanum.techandhttps://vscode.dev.Empty string: CORS disabled — no CORS headers, preflights are not answered.
Each entry is an exact origin (
scheme://host[:port], no path). A leading*.matches exactly one subdomain label:https://*.oceanum.ioallowshttps://app.oceanum.iobut nothttps://oceanum.io,https://a.b.oceanum.ioorhttps://oceanum.io.evil.com. Bare*, single-label wildcards (https://*.io) and malformed entries are rejected at startup; a scheme-default port (:443on https) is dropped, as browsers omit it. Multi-label public suffixes (https://*.co.uk,https://*.github.io) cannot be detected — never configure them: they would admit every site under that suffix.Credentials travel in
Authorization/X-DATAMESH-TOKENheaders, never cookies, soAccess-Control-Allow-Credentialsis never sent.Mcp-Session-IdandWWW-Authenticateare exposed to browser scripts.
claude.ai custom connectors
Set OCEANUM_MCP_PUBLIC_URL to the server's public base URL and the auto
and auth0 modes additionally serve OAuth 2.0 Protected Resource Metadata
(RFC 9728) naming the Auth0 tenant, plus a WWW-Authenticate challenge on
401s — which is how claude.ai discovers where to send users to authorize.
The Auth0 tenant must allow client registration for Claude (Dynamic Client
Registration, or a pre-registered application) and issue JWT access tokens
for the configured audience. Header/bearer clients are unaffected either way.
Post-deploy smoke test
scripts/smoke_hosted.py opens real gridded datasources over zarr through a
deployed server (load_datasource, and a whole-grid query_data), which
catches a broken data stack in the image that tools/list does not. There is
no deploy pipeline (the hosted service is deployed by hand with the local
deploy_cloudrun*.sh scripts), so run it manually after each deploy:
DATAMESH_TOKEN=<token> uv run python scripts/smoke_hosted.py https://mcp.oceanum.io/datameshThe token must be valid for the gateway the server uses. --load-datasource,
--query-datasource and --query-variable override the default datasets.
The URL must be https unless the host is local, since the token is sent with
every request. Exit status: 0 all checks passed; 1 a check failed, or the
server was unreachable or rejected the token; 2 usage error
(DATAMESH_TOKEN unset, or a non-https remote URL); 3 inconclusive (a
datasource was not found, not shared or empty, the query was refused, or it
was small enough to be downloaded instead of opened over zarr).
The hosted image installs this package from the source checkout
(pip install .), not from PyPI, so dependency fixes take effect on the next
deploy from main without a release.
Datamesh Tools
The intended workflow is: search_catalog → get_datasource_info → stage_query
(dry run: learn the result size without downloading) → query_data for small
results inline, or export_query to write large results to a file that analysis
code reads directly.
search_catalog
Search the Datamesh catalog with optional text search, time range, and bounding box filters.
Returns a JSON object with count and results; if count equals limit, more matches may exist.
Only datasources accessible to the request's credentials are searched. An empty or short
(below limit, with nothing omitted) result carries a fixed scope note saying a missing datasource either does
not exist or is not accessible with these credentials; it never reveals whether, how many,
or which inaccessible datasources exist.
By default each result is a compact summary: id, name, a description
cut to 200 characters, tstart/tend, bounds (rounded outward to 4
decimals), variable names when the catalog provides them (first 20, with
variables_total), and the first 5 tags (each clipped to 60 characters,
with tags_total). Unusable bounds (empty or non-finite) are null.
detail="full" returns each datasource's complete catalog record instead.
The response is compact JSON, and its total size is bounded (~20k characters
for summaries, ~100k for full records): matches beyond the bound are dropped,
counted in omitted, and a note asks to refine the search.
The catalog ranks datasources by fuzzy similarity to the search text and
returns the closest ones even when none contains it. With search text, the
response therefore carries text_matches: how many results have every
search word (as a whole word, singular or plural) in their id, name, description, tags, labels
or variable names. or separates alternatives and negated words or phrases (-era5, -"era5 grid",
not era5) are ignored. This count is only a signal: no result is dropped
for failing it, but results that fail are marked "text_match": false, and
a text_note ahead of the results explains. If no result contains the text
as whole words (text_matches: 0), every result is still returned, but in
summary mode as id and name only, with a text_note first and no
scope note.
Parameter | Type | Description |
| string | Text search for name, description, or tags |
| string | ISO 8601 start time |
| string | ISO 8601 end time |
| list[float] | Bounding box |
| int | Max results to return (default 20) |
| string |
|
get_datasource_info
Get the metadata for a datasource: coverage, schema dims and coordinates, variables, and attributes.
The default (detail="summary") is a compact view with the same fields as
the full record. Each variable and coordinate keeps its dims, shape,
dtype and units/long_name/standard_name attributes only (other
attributes are counted in attrs_omitted); the description is clipped to
1,000 characters, global attributes and info are capped at 25 entries
(with *_omitted counts), and long values are clipped to 200 characters.
schema.data_vars/schema.attrs are omitted as duplicates of
variables/attributes. Past ~30k characters the summary sheds, in order
and only as far as needed: global attributes, coordinate attributes,
variable attributes other than units, variable shape/dtype, and finally
per-variable details; the note names what was shed. Every variable name is
always listed. detail="full" returns the complete record. Both are compact
JSON.
An unknown id adds suggestions: visible datasources whose id or name
differs from the requested one by a typo (at most one character edit per 7 characters, up
to 3, with the differing words still similar), or extends a request of two
or more words. An id that merely shares generic words such as
oceanum_wave_..._era5, or a single word such as wave, is never
suggested.
Active notices about the datasource (see get_datasource_notices) come
first in both views: notices lists the outage and action_required ones
(e.g. a deprecation), outages first, then newest first, at most 5, as
severity, title, body
(markdown links and images reduced to their text, clipped to 500
characters) and expires_at, under a fixed notices_note that labels them
as announcements rather than instructions; notices_hint
counts any others ("at least N more" when the service sent its maximum of
20). These keys are absent when there are none, and the
record cannot supply them: a record field with one of their names is
renamed record_<name>. The summary view's size budget includes them.
The lookup never fails or holds up the tool: it runs alongside the metadata
request and is given at most 3 s in all; errors count as "no notices". There
is no lookup for an empty id. Set OCEANUM_MCP_DISABLE_NOTICES=1 to turn it
off.
Answers are cached per process, per credential and datasource, and shared
with get_datasource_notices; concurrent lookups for the same pair share
one request. A list of notices is reused for 10 minutes; no notices (an
empty list, or a 404: none visible) for 2 minutes, so a newly published
notice shows soon. A failure holds off further lookups of that datasource
for 1 minute (or the service's Retry-After, up to 10 minutes); a failure
of the service itself (a timeout, a connection error, a 5xx or 429) holds
off requests to it for every datasource, so a hung service costs one
timeout, not one per datasource. A refused credential or a 404 does not.
Meanwhile the last good answer is used, however old; with none,
get_datasource_info shows no notices. A failure never replaces the last
good answer, any success ends the hold-off, and running out of time before
the request is sent is not remembered. Notices that have expired, or are not yet published, are
dropped from every answer, cached or not. In the summary, a notice whose
title is only a link or image is left out (and counted in notices_hint).
Parameter | Type | Description |
| string | Datasource ID |
| string |
|
get_datasource_notices
Get the active notices about a datasource — deprecations, outages, changes
and other announcements published by Oceanum — in full, most severe first
(outage, action_required, then the rest), newest first within each, at
most 20. Returns {"datasource_id", "notices_note", "notices": [{severity, title, body, publish_at, expires_at}]}; severity is one of info,
change, action_required or outage, and body is markdown. notices is
empty when there are none, or when the datasource does not exist or is not
visible with your credentials. Any failure (no known admin service, no
credential, the service unreachable, slow, busy or rejecting the
credential) returns JSON with an error, plus retry_after_s when the
service asked to back off. While a recent failure holds off lookups (see
get_datasource_info), the tool answers from the last good answer without
asking the service, or, with none, with an error and retry_after_s: it
never reports "no notices" for a lookup that did not happen.
Notices come from the admin service (OCEANUM_ADMIN_SERVICE), called with
the same credential as the other tools: a Datamesh token as
X-DATAMESH-TOKEN, or in hosted mode an Auth0 JWT as Authorization: Bearer. So the credential only goes to a known admin service: unless
OCEANUM_ADMIN_SERVICE is set, notices are looked up only for the
datamesh.oceanum.io and datamesh.oceanum.tech services, and with any
other Datamesh service (local, staging) no request is made. Redirects are
never followed; a redirect or refused credential is logged as a warning
(at most every 10 minutes). Notice text is treated as untrusted whatever
the service sends: malformed notices are dropped, control and formatting
characters stripped, titles clipped to 200 characters and bodies to 2,000.
The lookup is given at most 3 s.
The notice text is still text an Oceanum administrator wrote, and it
reaches the model: the fixed notices_note labels it as announcements to
pass on, not instructions, and the summary in get_datasource_info drops
links, but nothing can stop a model from following instruction-like text it
reads. Notices are only as trustworthy as the admin service and the people
who publish them; OCEANUM_MCP_DISABLE_NOTICES=1 keeps them out of
get_datasource_info.
Parameter | Type | Description |
| string | Datasource ID |
stage_query
Dry-run a query on the Datamesh gateway: reports the result size, container
type, and domain length without downloading any data, echoes the canonical
query, and recommends the next step (inline query vs export vs narrowing).
The inline recommendation counts records as well as bytes: a result with more
records than OCEANUM_MCP_MAX_INLINE_ROWS would come back from query_data as
a preview, so it is steered to resampling, aggregation or export_query
instead. Accepts the same query parameters as query_data.
query_data
Query a datasource with filters and return small results inline as
coordinate-attributed JSON records with explicit truncated/lazy flags.
The query is staged first: gridded results above the inline limit are
summarized lazily (structure only); tabular results above the limit, and any
result above 1 GB, are refused with the staged size and alternatives (the
1 GB refusal also lists each variable's dims). The exception is limit
combined with time_resolution or aggregate_operations: the limited slice
may be small, so it is still opened lazily. Library warnings (e.g. the
2,000,000-row cap on tabular queries) are included in the response.
Parameter | Type | Description |
| string | Datasource to query |
| list[string] | Variables to select |
| string | ISO 8601 start of a time range (open-ended if omitted) |
| string | ISO 8601 end of a time range (open-ended if omitted) |
| list[string] | Discrete times (series selection); excludes |
| string | Server-side temporal downsampling (pandas frequency, e.g. |
| string | Resampling method for |
| list[float] | Bounding box |
| object | GeoJSON Feature (Point, MultiPoint, or Polygon) for selection |
| string | Interpolation for feature selection: nearest or linear |
| float | Max spatial resolution for downsampling, in CRS units |
| float | Minimum vertical level |
| float | Maximum vertical level |
| list[float] | Discrete vertical levels (series selection) |
| string | Interpolation for level series: nearest or linear |
| list[object] | Coordinate selections: |
| string/int | CRS for filter coordinates and returned data |
| list[string] | Aggregation ops: mean, min, max, std, sum |
| bool | Aggregate over spatial dims (default true) |
| bool | Aggregate over temporal dims (default true) |
| int | Keep the last N records (see below) |
limit keeps the last N records (Datamesh semantics: the last N steps along
time/ensemble), with the same meaning in stage_query, query_data, and
export_query. Combined with time_resolution or aggregate_operations it is
applied by this server after resampling/aggregation instead of being sent
to Datamesh (which would apply it to the native records first), so
stage_query reports the unlimited size as an upper bound. Hosted
export_query cannot apply it to a gateway download and refuses that
combination: drop limit or narrow the time range.
export_query
Export the full result of a query — the data-handle path for results too large to return inline. Behaviour depends on transport:
Local (stdio): writes the result to the local file
path(required) and returns that path. Gridded datasets stream lazily to NetCDF; tabular results write Parquet or CSV.Hosted (http/sse): returns a time-limited, self-authenticating gateway
download_url(chooseformat;pathis ignored). Fetch it out-of-band. When the response includesexpires_atormax_uses(gateways with scoped links), fetch it beforeexpires_atand at mostmax_usestimes. Results above 10 GB (for CSV, the estimated text size, about 3x the staged size) are refused (narrow the query); above 2 GB the link is returned with a large-download warning.
export_query sizes the result itself, whether or not stage_query was
called, and refuses before anything is exported. Results above the export cap
are refused outright: the cap limits the transfer, so splitting the request
into parts is not a way round it. An export that writes more than 1 GB in the
chosen format (CSV text is estimated at about 3x the staged size; locally, a
dataset written as CSV/Parquet is sized as the flattened table, and a limited
one on its limited slice) is refused unless confirm_size_bytes equals that
size. On hosted servers a value within 5% is accepted, because the download
stage is sized separately from stage_query's stage. The refusal reports the
exact value as export_size_bytes. The agent should pass it only after the
user has agreed. The server cannot see whether the user was asked, so the check
is advisory: it forces an explicit, size-aware step for each large export.
Accepts the same query parameters as query_data plus:
Parameter | Type | Description |
| string | Destination file path (parent directories are created) |
| string |
|
| bool | Overwrite an existing file (default false) |
| int | Bytes (in the chosen format) the user agreed to export; required above 1 GB; exact match (within 5% on hosted) |
load_datasource
Summarize an entire datasource. Gridded datasources are opened lazily (no data download); tabular datasources are downloaded only if under the inline size limit.
Parameter | Type | Description |
| string | Datasource to load |
update_metadata
Update metadata on an existing datasource. Only provided fields are changed.
Disabled when the server runs with OCEANUM_MCP_READ_ONLY set.
Parameter | Type | Description |
| string | Datasource to update |
| string | New name |
| string | New description |
| list[string] | New tags |
| list[string] | New labels |
| object | Additional metadata object |
| string | URL for datasource details |
Storage Tools
list_files
List files and directories in Oceanum cloud storage.
Parameter | Type | Description |
| string | Directory path to list (default: "/") |
| bool | List subdirectories recursively |
file_exists
Check if a file or directory exists in storage.
Parameter | Type | Description |
| string | Path to check |
read_file
Read the contents of a text file from storage.
Parameter | Type | Description |
| string | Path to the file |
write_file
Write text content to a file in storage.
Parameter | Type | Description |
| string | Destination path |
| string | Text content to write |
delete_file
Delete a file or directory from storage.
Parameter | Type | Description |
| string | Path to delete |
| bool | Delete directory contents recursively |
file_info
Get metadata about a file or directory.
Parameter | Type | Description |
| string | Path to inspect |
Example Workflows
Discover wave data in the Pacific:
search_catalog(search="wave", bbox=[120, -50, 180, 10])get_datasource_info(datasource_id="some-wave-dataset")stage_query(datasource_id="some-wave-dataset", variables=["Hs", "Tp"], time_start="2024-01-01", time_end="2024-01-31")to check the result sizequery_data(...)with the same parameters if small, orexport_query(..., path="waves.nc")if large
Shrink a 40-year hourly time series to something inline-sized:
stage_query(datasource_id="hindcast", variables=["Hs"], time_start="1984-01-01", time_end="2024-01-01")— too largequery_data(..., time_resolution="30D", time_resample="mean")— roughly monthly means, small enough to return inline (calendar aliases such as"1MS"are refused until a Datamesh engine fix ships: the engine currently reads"1MS"as 1 millisecond)
Browse and read files in cloud storage:
list_files(path="/")to see top-level contentslist_files(path="/my-project", recursive=True)to drill downread_file(path="/my-project/config.json")to read a file
Get a quick summary of a dataset:
get_datasource_info(datasource_id="my-dataset")to see variables and time rangequery_data(datasource_id="my-dataset", limit=10)to preview the data
Available Tools
13 toolsdatamesh_export_queryDatamesh Export QueryAIdempotent
Export the FULL result of a query — the data never enters the conversation.
Behavior depends on how the server is running:
Hosted (http/sse): returns a time-limited, self-authenticating gateway download_url (choose format via
format);pathis ignored. Fetch the URL out-of-band — it needs no credential, so treat it as a secret. When the response includes expires_at or max_uses, fetch it before expires_at and at most max_uses times. Refused above the hosted export cap, and for limit combined with time_resolution/aggregate_operations.Local (stdio): writes the result to the local file
path(required) and returns that path. Gridded datasets stream to NetCDF; tabular results write Parquet or CSV, as do datasets small enough to flatten into a table (e.g. point time series). Refused up front if the result exceeds the local export cap or the destination's free disk space. With limit plus time_resolution/aggregate_operations, the last N resampled steps are written.
The size is checked before anything is exported, whether or not stage_query was called. An export writing more than 1 GB in the chosen format (CSV text is about 3x; locally, a dataset written as CSV/Parquet is sized as the flattened table, and a limited one on its limited slice) is refused unless confirm_size_bytes equals that size (on hosted, within 5%, since the download stage is sized separately): ask the user first. The refusal states the exact value. The server cannot see whether the user was asked, so this is advisory: it forces an explicit, size-aware step. The export caps limit the transfer, not the size of each file: never split a refused request into parts to get under them.
A variable given as the exact CF standard_name of exactly one of the datasource's variables (e.g. "sea_surface_wave_significant_height" for "hs") is resolved to that variable; the response then includes resolved_variables ({requested: used}) and echoes the resolved names.
Inputs: datasource_id (required), crs, bbox, path, +21 more. Returns: result
datamesh_get_datasource_infoDatamesh Get Datasource InfoARead-only
Get the metadata for one datasource: coverage, coordinates and variables.
The default view keeps every field of the full record but reduces each variable and coordinate to its dims, shape, dtype, units, long_name and standard_name, clips the description and long attribute values, caps global attributes. On very large records it sheds attributes and then per-variable details (the note says which), but every variable name is always listed.
Inputs: datasource_id (required), detail. Returns: result
datamesh_load_datasourceDatamesh Load DatasourceARead-only
Summarize an entire datasource.
Gridded datasources are opened lazily (no data download). Tabular datasources are downloaded only if under the inline size limit; use query_data with filters to retrieve larger ones.
Inputs: datasource_id (required). Returns: result
datamesh_query_dataDatamesh Query DataARead-only
Query a datasource and return small results inline.
The query is staged first; results larger than the inline limit are not downloaded (datasets are summarized lazily, tabular queries are refused with alternatives), and results above 1 GB are refused with narrowing advice and each variable's dims, unless limit is combined with time_resolution/aggregate_operations (the limited slice may be small, so a dataset is then opened lazily). Use stage_query to size a query before calling this.
Inline values are a preview when preview is true (returned of total
records): never compute statistics from a preview; use
aggregate_operations or time_resolution instead.
limit keeps the last N records (Datamesh semantics: the last N steps along time/ensemble). Combined with time_resolution or aggregate_operations, limit is applied by this server AFTER resampling/aggregation (to the last N resampled steps, or the last N rows of a table) rather than sent to Datamesh. A limited result is a subset of the requested range, so it is flagged as a preview, with a limit_note.
A variable given as the exact CF standard_name of exactly one of the datasource's variables (e.g. "sea_surface_wave_significant_height" for "hs") is resolved to that variable; the response then includes resolved_variables ({requested: used}) and echoes the resolved names.
Inputs: datasource_id (required), crs, bbox, limit, +17 more. Returns: result
datamesh_search_catalogDatamesh Search CatalogARead-only
Search the Oceanum Datamesh catalog for datasets.
Catalog search only covers datasources accessible to the credentials used for this request; a datasource missing from the results either does not exist or is not accessible with these credentials, so do not report it as nonexistent.
Inputs: bbox, limit, detail, search, +2 more. Returns: result
datamesh_stage_queryDatamesh Stage QueryARead-only
Dry-run a query: report the result size WITHOUT downloading any data.
Always stage before retrieving data you have not sized. The response says whether the result is small enough for query_data to return inline, and echoes the canonical query. With limit plus time_resolution or aggregate_operations the reported size is that of the unlimited result (limit is applied after resampling), so it is an upper bound.
A variable given as the exact CF standard_name of exactly one of the datasource's variables (e.g. "sea_surface_wave_significant_height" for "hs") is resolved to that variable; the response then includes resolved_variables ({requested: used}) and echoes the resolved names.
Inputs: datasource_id (required), crs, bbox, limit, +17 more. Returns: result
datamesh_update_metadataDatamesh Update MetadataADestructiveIdempotent
Update metadata properties on an existing datasource.
Only the provided fields will be updated; others remain unchanged. Not available when the server runs with OCEANUM_MCP_READ_ONLY set.
Inputs: datasource_id (required), info, name, tags, +3 more. Returns: result
storage_delete_fileStorage Delete FileC
Delete a file or directory from Oceanum storage.
Inputs: path (required), recursive. Returns: result
storage_file_existsStorage File ExistsB
Check if a file or directory exists in Oceanum storage.
Inputs: path (required). Returns: result
storage_file_infoStorage File InfoB
Get metadata about a file or directory in Oceanum storage.
Inputs: path (required). Returns: result
storage_list_filesStorage List FilesC
List files and directories in Oceanum cloud storage.
Inputs: path, recursive. Returns: result
storage_read_fileStorage Read FileB
Read the contents of a text file from Oceanum storage.
Inputs: path (required). Returns: result
storage_write_fileStorage Write FileA
Write text content to a file in Oceanum storage.
Creates the file if it doesn't exist, overwrites if it does.
Inputs: path (required), content (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
The data-access tools are clearly tiered by role: search_catalog finds datasources, get_datasource_info/stage_query inspect metadata and size, query_data returns inline previews, and export_query offloads large results. The only real friction is load_datasource ('summarize an entire datasource') versus get_datasource_info ('metadata for one datasource'), which can look interchangeable at a glance, plus the storage_file_exists/storage_file_info pair.
Every name is snake_case with a clear domain prefix (datamesh_/storage_) and most follow verb_noun (query_data, export_query, stage_query, list_files, read_file, delete_file). The deviations are minor: load_datasource rather than get_datasource, and the noun-first storage_file_exists/storage_file_info.
Thirteen tools split cleanly into two domains (7 datamesh, 6 storage), each earning its place in the query/export workflow. Nothing feels redundant or padded at this size.
The data pipeline is covered end-to-end (discover → inspect → stage → query → export → update metadata) and storage has full create/read/list/delete/stat coverage. Gaps remain: no datasource creation or deletion, no storage copy/move, and metadata updates are the only write path for the catalog.
Maintenance
Related MCP Connectors
Access Pollinations models and API capabilities through agent tools.
Read Physical AI datasets, projects, fleet and quality data. Requires authorized Avala access.
Offline-first scientific and field tools for AI assistants: navigation, weather, geology, biology.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAccess oceanographic and environmental data from 63+ ERDDAP servers worldwide through natural language queries. Search datasets, retrieve metadata, and download scientific data for climate research, marine biology, and coastal management.18-

Code Ocean MCP Serverofficial
AlicenseBqualityBmaintenanceProvides tools to search and execute Code Ocean capsules and pipelines while managing platform data assets. It enables users to interact with Code Ocean's computational resources and scientific workflows directly through natural language interfaces.26298 PyPI5MIT- FlicenseCqualityDmaintenanceEnables LLMs to interact with ERDDAP search, metadata, and tabledap services for oceanographic data.51-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with the OSDU® data platform through Model Context Protocol, providing tools for search, storage, schema management, and dataset operations.2Apache 2.0