Utilities and errors¶

edi_ping¶

edi_ping is a liveness and capability report. It makes no upstream request unless asked to, so it is the first thing to call when a client connects or a tool fails unexpectedly.

Field	Meaning
`pong`	Always `ok`.
`version`, `protocolVersion`	edi-mcp version and the MCP revision it serves (`2026-07-28`).
`transport`	`stdio` or `http`.
`keyConfigured`	Whether this call has an EDI API key available. The key itself is never shown.
`keySource`	`config` (the server's environment or config file), `request` (an HTTP caller's `X-EDI-Key` header) or `none`.
`backend`	`pasta` with a key, `dataone` without one (see Backends).
`keyRequiredTools`	Registered tools that fail with `auth_required` without a key.
`downloadsEnabled`, `downloadDir`	Whether download tools are offered on this transport, and where they write.
`endpoints`	The PASTA, auth, DataONE and citation base URLs in use.
`api`	Present only with `check_api=true`.

With check_api=true edi-mcp makes one small request to the backend serving the caller — with a key, it exchanges the key for a token and lists PASTA's scopes; without one, it runs a zero-row DataONE query — and reports in api:

Field	Meaning
`reachable`	Whether the backend answered.
`backend`	The backend that was checked.
`credential`	`token` (an `edi-token` cookie), `key` (the key as a query parameter, used only when EDI's auth service is unreachable) or `none` (DataONE).
`endpoint`, `latencyMs`	The request made and how long it took.
`error`	The error `code` and `message` when the check failed, e.g. `upstream_forbidden` for a rejected key.

edi-mcp --check calls edi_ping in-process and prints the report as JSON. It stays offline; the live check is edi_ping(check_api=true).

Error codes¶

A failed tool call returns isError: true and structuredContent.error = {code, message, details, hint?}. code is stable and machine-readable; message is safe to show a user and never contains a key or token; hint, when present, is a one-line remedy.

Code	Meaning	What to do
`invalid_argument`	The arguments failed validation, an identifier could not be parsed, or the upstream rejected the request (HTTP 400).	Fix the argument; `details` names the problem and, for identifiers, lists the accepted forms.
`not_found`	No such package, scope, revision or resource (HTTP 404/410), or a scope name matched nothing.	Check the identifier; scope misses include `didYouMean`.
`ambiguous_input`	A scope name or location matches several scopes about equally.	Pick one of the ranked `candidates` and pass its exact scope.
`auth_required`	The operation needs an EDI API key and none is available for this call.	Set `EDI_API_KEY` (stdio) or send `X-EDI-Key` (HTTP); `details.guide` points at `edi://guide/api-key`.
`upstream_forbidden`	A key was sent and EDI refused. Without `reason` (HTTP 401) the key was rejected; with `reason: access_restricted` (HTTP 403) the key works but the package is restricted to named users or groups.	Replace the key, or for a restricted package ask its contact for access. edi-mcp never falls back to DataONE here.
`rate_limited`	The upstream answered HTTP 429.	Wait `details.retryAfterSeconds` before retrying.
`upstream_error`	The upstream failed (HTTP 5xx), answered with an unexpected status, or returned a body that could not be parsed.	Retry later; `details` carries the status and endpoint.
`upstream_unavailable`	The upstream could not be reached (network error or timeout).	Retry in a moment; call `edi_ping(check_api=true)`.
`result_too_large`	A result stayed above the hard size limit after trimming, or an upstream response exceeded the byte cap.	Narrow the request: a smaller `limit` or a narrower search.
`unknown_tool`	No tool has that name.	`details.available` lists the tools.
`internal_error`	A bug in edi-mcp.	Report it with the request id.
`feature_unavailable`	Reserved: a feature disabled by configuration.	—
`not_available_in_http_mode`	Reserved for the stdio-only download tools (Roadmap).	Use a stdio deployment.
`download_limit_exceeded`, `download_denied`, `checksum_mismatch`	Reserved for the download tools (Roadmap): a per-call limit, a path or host outside what is allowed, and a file whose SHA-1 differs from the one EDI publishes.	—

Results that are merely large are not errors: lists are trimmed to fit the result budget (50,000 bytes by default) and report page.truncatedReason: budget with a nextOffset to continue from.