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
datamesh	Search, query, and manage ocean/environmental datasets
storage	List, read, write, and delete files in Oceanum cloud storage
combined	All tools from both servers under a single endpoint (default)

Prerequisites

Get an API token from oceanum.io. Set it as the DATAMESH_TOKEN environment variable.

Installation

pip install oceanum-mcp

Or run directly with uvx:

uvx oceanum-mcp              # combined server (default)
uvx oceanum-mcp datamesh     # datamesh only
uvx oceanum-mcp storage      # storage only
uvx oceanum-mcp --list       # show available servers

Configuration

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": ["oceanum-mcp"],
      "env": {
        "DATAMESH_TOKEN": "your-token-here"
      }
    }
  }
}

Individual server (datamesh only):

{
  "mcpServers": {
    "oceanum-datamesh": {
      "command": "uvx",
      "args": ["oceanum-mcp", "datamesh"],
      "env": {
        "DATAMESH_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Code

# Combined server
claude mcp add --transport stdio oceanum -- uvx oceanum-mcp

# Individual server
claude mcp add --transport stdio oceanum-datamesh -- uvx oceanum-mcp datamesh

Set the token in your environment:

export DATAMESH_TOKEN=your-token-here

VS Code / Cline / Continue

Use stdio transport with the same command:

{
  "command": "uvx",
  "args": ["oceanum-mcp"],
  "env": {
    "DATAMESH_TOKEN": "your-token-here"
  }
}

Environment Variables

Variable	Required	Description
DATAMESH_TOKEN	Yes	Oceanum API token (shared by all servers)
DATAMESH_SERVICE	No	Custom datamesh service URL (default: https://datamesh.oceanum.io)
STORAGE_SERVICE	No	Custom storage service URL (default: https://storage.oceanum.io)
OCEANUM_DOMAIN	No	Override the base domain for all services (default: oceanum.io)
OCEANUM_MCP_READ_ONLY	No	Set to 1/true to disable write tools (update_metadata, storage write_file/delete_file)
OCEANUM_MCP_MAX_INLINE_BYTES	No	Max staged result size returned inline by query_data (default 50,000,000)
OCEANUM_MCP_MAX_INLINE_ROWS	No	Max rows/records previewed inline before truncation (default 100)
OCEANUM_MCP_EXPORT_DIR	No	If set, export_query may only write inside this directory
OCEANUM_MCP_AUTH	No	Auth scheme for --transport http: auto (default), datamesh, auth0, or none
OCEANUM_MCP_AUTH0_DOMAIN	No	Auth0 tenant domain for auth0 mode (default: auth.oceanum.io)
OCEANUM_MCP_AUTH0_AUDIENCE	No	Auth0 API audience for auth0 mode (default: https://api.oceanum.io)
OCEANUM_MCP_PUBLIC_URL	No	Externally visible base URL (e.g. https://mcp.oceanum.io); enables OAuth discovery metadata for claude.ai connectors

DATAMESH_TOKEN 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 8000

This 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 the X-DATAMESH-TOKEN header (the same header the gateway itself uses), Auth0 JWTs in Authorization: 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 own DATAMESH_TOKEN. Only for trusted-network deployments.

Notes:

• export_query works 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 gateway download_url that the caller fetches out-of-band. The path argument is ignored on hosted servers. The URL needs no credential, so it is a capability — treat it as a secret.
• Combine with OCEANUM_MCP_READ_ONLY=1 to run a read-only public service.
• Pass --stateless when 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 no export_query. Set OCEANUM_MCP_AUTH=none to 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 8000

Requests 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.

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.

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.

Parameter	Type	Description
search	string	Text search for name, description, or tags
time_start	string	ISO 8601 start time
time_end	string	ISO 8601 end time
bbox	list[float]	Bounding box [xmin, ymin, xmax, ymax] in WGS84
limit	int	Max results to return (default 20)

get_datasource_info

Get full metadata for a datasource including schema, variables, coordinates, and attributes.

Parameter	Type	Description
datasource_id	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). 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 are refused with the staged size and alternatives. Library warnings (e.g. the 2,000,000-row cap on tabular queries) are included in the response.

Parameter	Type	Description
datasource_id	string	Datasource to query
variables	list[string]	Variables to select
time_start	string	ISO 8601 start of a time range (open-ended if omitted)
time_end	string	ISO 8601 end of a time range (open-ended if omitted)
times	list[string]	Discrete times (series selection); excludes time_start/time_end
time_resolution	string	Server-side temporal downsampling (pandas frequency, e.g. 1D)
time_resample	string	Resampling method for time_resolution: mean, nearest, linear
bbox	list[float]	Bounding box [xmin, ymin, xmax, ymax]
geofilter_feature	object	GeoJSON Feature (Point, MultiPoint, or Polygon) for selection
geofilter_interp	string	Interpolation for feature selection: nearest or linear
geofilter_resolution	float	Max spatial resolution for downsampling, in CRS units
level_min	float	Minimum vertical level
level_max	float	Maximum vertical level
levels	list[float]	Discrete vertical levels (series selection)
level_interp	string	Interpolation for level series: nearest or linear
coord_filters	list[object]	Coordinate selections: [{"coord": "name", "values": [...]}]
crs	string/int	CRS for filter coordinates and returned data
aggregate_operations	list[string]	Aggregation ops: mean, min, max, std, sum
aggregate_spatial	bool	Aggregate over spatial dims (default true)
aggregate_temporal	bool	Aggregate over temporal dims (default true)
limit	int	Max rows to return

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 (choose format; path is ignored). Fetch it out-of-band.

Accepts the same query parameters as query_data plus:

Parameter	Type	Description
path	string	Destination file path (parent directories are created)
format	string	netcdf (datasets), parquet or csv (tabular); sensible default
overwrite	bool	Overwrite an existing file (default false)

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
datasource_id	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
datasource_id	string	Datasource to update
name	string	New name
description	string	New description
tags	list[string]	New tags
labels	list[string]	New labels
info	object	Additional metadata object
details	string	URL for datasource details

Storage Tools

list_files

List files and directories in Oceanum cloud storage.

Parameter	Type	Description
path	string	Directory path to list (default: "/")
recursive	bool	List subdirectories recursively

file_exists

Check if a file or directory exists in storage.

Parameter	Type	Description
path	string	Path to check

read_file

Read the contents of a text file from storage.

Parameter	Type	Description
path	string	Path to the file

write_file

Write text content to a file in storage.

Parameter	Type	Description
path	string	Destination path
content	string	Text content to write

delete_file

Delete a file or directory from storage.

Parameter	Type	Description
path	string	Path to delete
recursive	bool	Delete directory contents recursively

file_info

Get metadata about a file or directory.

Parameter	Type	Description
path	string	Path to inspect

Example Workflows

Discover wave data in the Pacific:

1. search_catalog(search="wave", bbox=[120, -50, 180, 10])
2. get_datasource_info(datasource_id="some-wave-dataset")
3. stage_query(datasource_id="some-wave-dataset", variables=["Hs", "Tp"], time_start="2024-01-01", time_end="2024-01-31") to check the result size
4. query_data(...) with the same parameters if small, or export_query(..., path="waves.nc") if large

Shrink a 40-year hourly time series to something inline-sized:

1. stage_query(datasource_id="hindcast", variables=["Hs"], time_start="1984-01-01", time_end="2024-01-01") — too large
2. query_data(..., time_resolution="1MS", time_resample="mean") — monthly means, small enough to return inline

Browse and read files in cloud storage:

1. list_files(path="/") to see top-level contents
2. list_files(path="/my-project", recursive=True) to drill down
3. read_file(path="/my-project/config.json") to read a file

Get a quick summary of a dataset:

1. get_datasource_info(datasource_id="my-dataset") to see variables and time range
2. query_data(datasource_id="my-dataset", limit=10) to preview the data