CASDA MCP Server

casda-mcp is a conservative Model Context Protocol server for the CSIRO ASKAP Science Data Archive (CASDA). It converts an AI client's structured selections into explicit, auditable archive operations. The server does not interpret unrestricted natural language or expose URL-fetching, shell, or filesystem browsing tools. Advanced ADQL is optional and flag-gated (CASDA_ENABLE_ADVANCED_ADQL).

The supported workflow is:

1. Discover archive status, schemas, and VO holdings (VOSI, SIA/SCS/SSA, projects, events).

2. Search bounded CASDA ObsCore metadata or run validated advanced ADQL when enabled.

3. Inspect one product, ASKAP scheduling block, project, or collection.

4. Select explicit product identifiers.

5. Optionally submit authenticated SODA/UWS full-file, cutout, or spectrum jobs.

6. Check that request with a separate, single status call (casda_get_data_job / staging alias).

7. Optionally download archive-confirmed files into a restricted directory.

8. Create a reproducible JSON manifest with collection metadata.

Search and metadata inspection are enabled by default. Staging, downloads, and advanced ADQL are disabled by default and require separate administrator configuration.

Status and confirmed interfaces

The implementation uses these CASDA interfaces:

• TAP 1.0/ADQL (sync and async) with VOSI availability/capabilities and TAP_SCHEMA discovery;

• SIA 2, SIA 1 (+ surveys), SCS catalogue cone search, and SSA spectrum discovery;

• public observation events feed;

• Datalink 1.1 VOTables for authenticated SODA service and opaque product-token discovery;

• asynchronous SODA/UWS jobs for full-file staging, cutouts, spectrum generation, and one-shot status;

• archive result URLs and checksum sidecars for streamed downloads.

Public metadata paths were validated live on 18 July 2026. Optional -m live tests exercise read-only discovery when CASDA_RUN_LIVE_TESTS=true. Authenticated staging, cutout, and downloads are covered by mocked protocol tests and are never run by default live gates.

The dated CASDA capability matrix maps the complete public and authenticated protocol surface, implementation status, remaining upstream/DAP boundaries, and MCP contract requirements.

Related MCP server: Cassini Mission Plan MCP

Requirements

• Python 3.10 or newer

• uv for the documented locked setup

• Network access to the configured CASDA endpoints

• An OPAL account only for staging operations

Installation

git clone <repository-url> casda-mcp
cd casda-mcp
uv sync --frozen --extra dev

Run the server over stdio:

uv run casda-mcp

Run the Streamable HTTP transport on loopback:

uv run casda-mcp --transport streamable-http --host 127.0.0.1 --port 8000

The MCP endpoint is http://127.0.0.1:8000/mcp. Non-sensitive probes:

• http://127.0.0.1:8000/healthz — process liveness

• http://127.0.0.1:8000/readyz — readiness using last-known archive availability (never blocks on a live CASDA call)

MCP client configuration

For a stdio client, adjust the absolute project path:

{
  "mcpServers": {
    "casda": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/casda-mcp",
        "run",
        "casda-mcp"
      ],
      "env": {
        "CASDA_ENABLE_STAGING": "false",
        "CASDA_ENABLE_DOWNLOADS": "false"
      }
    }
  }
}

Codex CLI can register the same stdio command:

codex mcp add casda \
  --env CASDA_ENABLE_STAGING=false \
  --env CASDA_ENABLE_DOWNLOADS=false \
  -- uv --directory /absolute/path/to/casda-mcp run casda-mcp

Equivalent Codex config.toml:

[mcp_servers.casda]
command = "uv"
args = ["--directory", "/absolute/path/to/casda-mcp", "run", "casda-mcp"]

[mcp_servers.casda.env]
CASDA_ENABLE_STAGING = "false"
CASDA_ENABLE_DOWNLOADS = "false"

ChatGPT desktop and IDE MCP settings accept either the same STDIO command or the Streamable HTTP URL. Restart the client after adding the server. See the current ChatGPT MCP configuration guide.

Configuration

Configuration is loaded from environment variables and validated at startup. Invalid state-changing configuration fails fast.

Copy .env.example to .env for local development; it is loaded automatically and ignored by Git. Do not commit a populated .env file. Production deployments should inject secrets instead.

Enabling staging

export CASDA_USERNAME='researcher@example.edu.au'
export CASDA_PASSWORD='use-a-secret-provider-in-production'
export CASDA_ENABLE_STAGING=true
uv run casda-mcp

Use the process environment, an OS credential provider that injects environment variables, or a deployment secret store. Do not put credentials in command-line arguments. The implementation uses the OPAL HTTP Basic authentication behavior confirmed by Astroquery's CASDA client.

Enabling downloads

export CASDA_ENABLE_DOWNLOADS=true
export CASDA_DOWNLOAD_DIR=/srv/casda-downloads
export CASDA_MAX_DOWNLOAD_BYTES=10737418240
uv run casda-mcp

The directory must be absolute, dedicated to CASDA downloads, and cannot resolve to a filesystem root. On POSIX it must be owned by the server account and not group- or world-writable; equivalent ACL isolation is an operator responsibility on Windows. Its canonical location and inode identity are recorded once writes begin and rechecked before path mutations; non-sticky writable ancestors are rejected on POSIX. Caller destinations are checked for containment, symlink traversal, reserved internal names, and portable filename safety. Each target is reserved in a private, hash-named .casda-mcp/locks directory before any archive request. Files are streamed as identity-encoded raw bytes through a descriptor bound to the original temporary inode, then published atomically after length and optional checksum verification. With overwrite disabled, the destination filesystem must support same-directory hard links for atomic no-clobber publication. Incomplete files and normal reservations are removed after failure.

Tools

Successful tool responses carry operation-specific data and provenance. Failures use protocol-level ToolError / isError rather than a successful envelope with an error field. Provenance contains the server version, archive, timestamps, deterministic query identifier, sanitised endpoint, parameters, result count, cache status, and correlation identifier. Credentials and URL query strings are not included.

Discovery and job tools beyond the core ObsCore path include:

The full name inventory is asserted in tests/test_contract.py.

casda_search_products

Read-only bounded product discovery. Supported filters are exact source/target name, ICRS position and radius in degrees, OPAL project code, ASKAP SBID, overlapping ISO 8601 observation dates, overlapping frequencies in hertz, exact collection, facility/instrument names, and these allowlisted product types:

image, cube, visibility, spectrum, catalogue, weight, moment_map, cubelet, evaluation, scan.

It supports bounded pagination (page or opaque cursor) and allowlisted sorting. It does not resolve astronomical names, stage, or download. Caller-supplied ADQL belongs on the flag-gated advanced tools, not this helper.

{
  "ra_deg": 333.8,
  "dec_deg": -46.0,
  "radius_deg": 0.05,
  "project_code": "AS102",
  "product_types": ["cube", "weight", "moment_map"],
  "released_only": true,
  "page": 1,
  "page_size": 20
}

casda_get_product

Read-only complete supported ObsCore metadata for one exact obs_publisher_did.

{"product_id": "cube-1170"}

The response retains raw archive identifiers, nulls, units in field names, spatial footprint, spectral coverage converted to hertz, estimated byte size, SBID when encoded as ASKAP-<sbid>, project code where the collection maps to casda.project.short_name, release state, and quality.

casda_get_observation

Read-only ASKAP observation lookup with related projects and a bounded product list.

{"scheduling_block_id": 2338}

casda_stage_products

Creates and starts one archive-side asynchronous SODA/UWS request. It requires staging to be enabled and OPAL credentials to be present. Empty requests are rejected, identifiers are normalised and deduplicated, count and total estimated size are bounded, and missing sizes are rejected by default.

{
  "product_ids": ["cube-1170", "cube-1171"],
  "idempotency_key": "wallaby-run-2026-07-12",
  "allow_duplicate": false
}

The output includes the archive request ID, effective idempotency key, confirmed phase, submission time, and per-product state. A reused idempotency key with different products is an error. An active request for the same product set is returned rather than duplicated unless the caller uses a new key and explicitly sets allow_duplicate.

The non-idempotent archive creation and start requests are never automatically retried.

casda_stage_pawsey

Creates and starts one Pawsey pull staging job via the DataLink pawsey_async_service descriptor. Requires the same CASDA_ENABLE_STAGING flag and OPAL credentials as WEB full-file staging, but results are Pawsey-network restricted. The response includes human_gate_warnings: a Pawsey HPC account is required, and licence/account confirmation must be completed by a human in the DAP — this server never auto-accepts terms. Reuse casda_get_data_job / download tools for lifecycle.

casda_resolve_collection_doi

Read-only public citation resolve. Provide exactly one of doi, collection, or project_code. DOIs are fetched from DataCite JSON with a doi.org CSL-JSON fallback on allowlisted hosts only. Collection/project lookups never invent a DOI; when archive metadata has none, the tool returns found=false plus a DAP search navigation URL. CSIRO DAP DOIs typically use prefix 10.25919 (is_csiro_dap). Never mints DOIs.

casda_get_dap_navigation

Constructs documented DAP deep links (Observation Search, Skymap, search hints) without scraping HTML. Privileged action values such as accept_licence, mint_doi, or launch_carta return structured unsupported_actions only — never HTTP mutation.

casda_get_staging_status

Performs exactly one uncached UWS status read:

{"request_id": "archive-job-id"}

It returns the overall archive phase, expiry, archive failure reason, per-product state, and whether every product has a confirmed matching result URL. Active phases advise the caller to make another tool call later; no background polling is claimed or scheduled.

casda_download_product

Downloads one product only after a completed status read recorded a matching archive result URL:

{
  "product_id": "cube-1170",
  "destination": "wallaby/cube-1170.fits",
  "verify_checksum": true
}

The result includes the confirmed local path, actual bytes, Content-Length verification, checksum result, whether a Range retry resumed within this call, staging request ID, and provenance. A local path is never returned before the final file exists. The server does not expose a deletion tool.

casda_create_cutout / casda_create_spectrum

Authenticated SODA jobs (require staging enabled + OPAL). Supply CIRCLE / POLYGON / BAND / CHANNEL / POL / COORD as documented by CASDA DataLink descriptors. Monitor with casda_get_data_job, then download via casda_download_product or casda_download_job_results.

casda_create_manifest

Creates and retains a schema-versioned JSON manifest in server state:

{
  "product_ids": ["cube-1170", "catalogue-10"],
  "source_name": "WALLABY J2214-4600",
  "workflow_name": "spectral-line-analysis",
  "include_download_urls": false
}

The manifest includes a deterministic SHA-256 identifier, creation time, full typed product metadata, filenames, estimated file sizes, available checksums, SBIDs, project codes, types, spatial and spectral metadata, access state, collection metadata (obs_collection, facility_name, release span), known originating search criteria, provenance, and server version. Archive artifact URLs are never persisted in manifests because opaque paths may be short-lived bearer credentials even when they contain no query string. Use casda_resolve_collection_doi for public citation metadata.

Resources

The server exposes read-only resources:

• casda://products/{product_id}

• casda://observations/{scheduling_block_id}

• casda://staging/{request_id}

• casda://events/{event_id}

• casda://manifests/{manifest_id}

• casda://archive/status

• casda://archive/capabilities

• casda://dap/navigation

• casda://server/status

• casda://skills (JSON index of packaged agent skills)

• casda://skills/{skill_name} (raw SKILL.md markdown)

Resources do not expose credentials, raw local state files, unrestricted filesystem content, or URL query strings. The staging resource performs one current status read, like the tool.

Prompts

Registered MCP prompts guide safe workflows:

Agent skills

Canonical skill files live under src/casda_mcp/skills/ and ship in the package:

• casda-safe-archive-access

• casda-find-and-inspect

• casda-stage-and-download

• casda-reproducible-manifest

The same files are mirrored under .cursor/skills/ for Cursor project discovery. MCP clients can read them through casda://skills and casda://skills/{skill_name}.

Example workflows

Search and inspect

1. Call casda_search_products with explicit bounded criteria.

2. Present the candidates and stable product identifiers to the researcher.

3. Call casda_get_product only for selected identifiers.

4. Explain access_state and authorisation_state without claiming access that CASDA has not confirmed.

Search by WALLABY source

1. Resolve the source name to coordinates in the AI client or a separately trusted resolver.

2. Call casda_search_products with the explicit coordinates, radius, project_code: "AS102", and required product types.

3. Inspect candidates, including SBID, collection, footprint, spectral range, and file size.

4. Call casda_create_manifest for the explicit selection.

The generic model can represent WALLABY identifiers present in target_name, project code, SBID, footprint, cube/weight/catalogue/spectrum/moment-map subtypes, channels, spatial metadata, size, and access state. No wallaby_find_source_products tool is included because a stable, complete source selection rule has not been established. WALLABY-specific rules should remain a future adapter.

Stage and download

1. Inspect the selected product and size.

2. Call casda_stage_products for WEB download staging, or casda_stage_pawsey for Pawsey pull (read human_gate_warnings; complete licence/HPC confirmation as a human in the DAP).

3. Later, call casda_get_staging_status or casda_get_data_job; do not assume automatic polling.

4. Only after products are ready, call casda_download_product (Pawsey results are network-restricted).

5. Check returned length and checksum fields.

Cutout

1. Enable staging and configure OPAL credentials.

2. Call casda_create_cutout with an explicit product_id and SODA constraints (for example circle).

3. Poll with casda_get_data_job.

4. Download with casda_download_product or casda_download_job_results when downloads are enabled.

Advanced ADQL

1. Set CASDA_ENABLE_ADVANCED_ADQL=true.

2. Prefer casda_build_adql or carefully drafted SELECT-only ADQL.

3. Call casda_validate_adql, then casda_tap_query or casda_submit_tap_query.

4. Prefer casda_search_products / VO discovery tools when allowlisted filters suffice.

Reproducible workflow manifest

1. Search with explicit criteria.

2. Select identifiers.

3. Inspect full metadata.

4. Call casda_create_manifest.

5. Read the result later through casda://manifests/{manifest_id} when persistent state is enabled.

Security model

• Tool input is untrusted and validated before query construction.

• TAP table names, selected columns, product-type clauses, sort fields, and operators are hard-coded allowlists.

• Text wildcards and control characters are rejected; identifiers use restrictive patterns.

• Cone, result, page, staging, manifest, decoded archive response, and download sizes are bounded.

• Only configured HTTPS CASDA hosts and current CASDA-controlled Pawsey download hosts are allowed. Redirect destinations are revalidated before they are followed.

• Safe metadata reads may retry; staging creation/start never automatically retry.

• OPAL credentials use environment/secret injection and are excluded from logs, provenance, and exceptions.

• Structured logs go to stderr so stdio JSON-RPC is not corrupted.

• Cache keys include the complete generated query and bound; authentication failures are not cached.

• Staging status is never cached.

• Streamable HTTP binds to loopback by default and has no built-in client authentication. Put a production remote deployment behind TLS and an authenticating reverse proxy or MCP authorization layer. Do not expose it directly when staging, credentials, or downloads are enabled.

• Principal isolation is process-scoped: credentials, authorization results, job state, ready URLs, caches, and manifests are not multiplexed safely across remote users in one process. For remote multi-user deployments, run one process per principal (or an equivalent front end that never shares a process across principals).

• CASDA_STATE_DB may contain short-lived signed URLs needed to resume status/download workflows. The server rejects symlink/non-file targets and forces owner-only file permissions on POSIX; deployments should additionally use an owner-controlled directory and encrypted storage. In-memory state is the default.

See SECURITY.md for the threat model and reporting guidance.

Architecture

MCP client
  -> typed FastMCP tools/resources/prompts
  -> CasdaService (validation, limits, idempotency, provenance)
  -> QueryBuilder / adql / vosi / cursor / parsers / TTL cache / StateStore
  -> CasdaClient (pooled HTTP, retries, host validation, OPAL auth)
  -> CASDA TAP | VOSI | SIA/SCS/SSA | events | Datalink | SODA/UWS | staged file endpoint

The modules are deliberately separated so CASDA protocol behavior does not depend on a particular AI client. See docs/architecture.md for component and sequence details. See docs/casda-capability-matrix.md for protocol coverage and the implementation roadmap.

Testing and validation

Run the default offline suite:

uv run pytest -m "not live" --cov=casda_mcp --cov-report=term-missing
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv build

The tests cover validation, coordinates, cone limits, dates, frequencies, identifiers, safe ADQL, pagination, CSV/VOTable/UWS parsing, redaction, caching, error mapping, idempotency, partial staging, path traversal, overwrite prevention, streamed byte limits, checksum mismatch cleanup, Range resume, manifest determinism, MCP schemas, resources, health, and mocked end-to-end HTTP behavior.

Optional live tests are read-only discovery checks and disabled by default:

CASDA_RUN_LIVE_TESTS=true uv run pytest -m live -v

They cover VOSI availability/capabilities, a small TAP sync query, schema listing, SIA 2 cone, SIA 1 surveys, catalogue inventory, and the events feed. They never stage, download, or create cutouts. CI does not require credentials.

Container

Build and run the default read-only HTTP server:

docker build -t casda-mcp .
docker run --rm -p 127.0.0.1:8000:8000 casda-mcp

The image runs as a non-root user and checks /healthz. Mount a dedicated directory and inject secrets only when explicitly enabling downloads or staging.

Troubleshooting

• No products: remove filters deliberately, check the exact target/collection name, and keep the radius explicit. The server will not silently broaden the request.

• ARCHIVE_QUERY_ERROR: CASDA rejected the generated bounded query. Record the correlation and query IDs; no stack trace or credentials are exposed to the client.

• AUTHENTICATION_REQUIRED / AUTHENTICATION_FAILED: configure both OPAL variables and verify the account at the OPAL site. Metadata search itself does not require login.

• STAGING_DISABLED / DOWNLOADS_DISABLED: these are safe defaults, not archive failures.

• STAGING_REQUEST_NOT_FOUND: in-memory state was lost after restart or the ID came from another instance. Configure CASDA_STATE_DB before submission when restart persistence is required.

• PRODUCT_NOT_READY: run a current status check for the original request. The server will not infer readiness from elapsed time.

• UNSAFE_ARCHIVE_URL: CASDA returned a host outside the configured allowlist. Do not bypass this check without verifying a documented archive migration.

• Repeated stale metadata: reduce/disable the short cache or restart; staging status bypasses it.

• HTTP works but remote access should not: the default bind is loopback. Remote exposure requires an explicit host plus a secure front end.

Known limitations

• Authenticated staging, cutout, spectrum, and file download behavior is protocol-tested with mocks; default live tests never exercise those paths.

• ASKAP SBID product relationships use the confirmed ObsCore obs_id = 'ASKAP-<sbid>' convention.

• Project codes are joined where ivoa.obscore.obs_collection matches casda.project.short_name; CASDA does not expose a direct generic project foreign key in ObsCore.

• CASDA's current ADQL service does not support CURRENT_TIMESTAMP; public-only search retrieves the configured bounded window and removes future release dates locally.

• Advanced ADQL remains SELECT-only, length/row bounded, and disabled until CASDA_ENABLE_ADVANCED_ADQL=true.

• UWS reports an overall job phase. A product is marked individually ready only when a completed job returns its unique product result identifier. A globally unambiguous filename fallback is retained for historical jobs; ambiguous results remain UNKNOWN.

• Resumption is attempted within one download call only when CASDA supplies a strong ETag or an RFC-strong Last-Modified validator; otherwise a retry restarts from byte zero. Final failure removes the temporary file, so resumption does not persist across separate calls. An abrupt process or host termination can leave a hashed lock in .casda-mcp/locks that an operator must inspect and remove before retrying that exact destination.

• Source-name resolution is outside this server. DOI minting, licence acceptance, and other privileged DAP workflows remain DAP-boundary; use casda_resolve_collection_doi and casda_get_dap_navigation for safe read-only helpers.

• Beam identifiers may be retained in filenames or target metadata, but CASDA ObsCore does not expose a generic structured neighbouring-beam relationship used by this implementation.

References

• CASDA user guide

• CASDA capability matrix

• Astroquery CASDA module

• CASDA VO Tools

• Model Context Protocol server guide