MCP tool reference

The versioned MCP catalog is generated from the Go tool registry and DTO schemas. It is the source for exact names, arguments, effects and schemas. The available catalog follows your OAuth scopes and deployment feature gates. Every project operation checks your current permissions for its explicit project ID. Do not treat an old tool list as permission to call a tool.

Project discovery

list_projects is the only tool that does not require project_id. It lists active, MCP-enabled projects accessible to the signed-in user across organizations, including their project and organization identities. Disabled, archived and inaccessible projects are omitted. Use the returned IDs with all subsequent tools; discovery does not lock the connection to one project.

The exact discovery arguments and output are defined in the generated catalog. See the MCP guide for the combined MCP and skills installer.

Read workflows

Start with list_projects to discover enabled projects across your organizations. Select the intended project, then call get_project_context with its project_id. Discover authorized instruments before selecting IDs, inspect their schema, then query an explicit bounded time range. Inspect saved dashboards and query only saved supported widgets using the server’s projections. Ingestion run diagnostics require their own scope and permission. Documentation search and reads supply canonical integration guidance even without a plugin.

Every tool except list_projects requires project_id, including documentation tools and writes. The server derives the organization from the selected project and checks current access and MCP policy. Resource URLs, nested IDs, cursors and handles remain bound to that project and grant. A cursor cannot be moved to a different project or query. Follow a returned cursor only with the same query; request smaller ranges if the server reports a limit. Never silently drop returned warnings or treat truncation as a complete export.

Results retain units, quality/missingness and provenance; timestamps normalize to UTC. Read results are bounded by rows, bytes, query range and deadlines. Review the returned bounds and catalog schema for the current version. Permission-dependent lists and project data use private cache scope with zero initial TTL; cached metadata is not an authorization mechanism.

Errors and writes

Missing or invalid credentials return an HTTP Bearer challenge for user-scoped OAuth metadata for the single /mcp resource. Reconnect after a 401 as the client directs. Permission denial requires checking current user permission and grant scope; repeated retries do not fix it. Invalid arguments or limit failures require a corrected, bounded request. Retry a transient failure only with bounded backoff and the same intended operation.

Write tools are omitted until separately released with consent, permission, revision, idempotency and audit gates. A JSON-RPC request ID is not an idempotency key. Do not infer a mutation from a read-only workflow or substitute a Developer API key for a missing MCP permission. The existing Developer API remains a separate interface with supported writes; ingestion is asynchronous and uses its own credential.

Gated writes

When a deployment enables writes and your grant and current administrative permissions allow them, these narrow contracts are available in gated_tools in the generated catalog:

• create_dashboard: create a named dashboard, optionally with up to 20 typed graph, table, or Markdown widgets. New widgets and entries use client_id; the response identifies saved widget IDs.
• update_dashboard: rename or upsert complete typed widget definitions with expected_revision. Omitted widgets remain, and existing widget types cannot change. No deletion or archive action is hidden in this patch.
• create_instrument: create a named instrument in an active site in the selected project.
• preview_calculated_variable: validate a single undated formula with 1–10 explicit variable or constant inputs. It returns a ten-minute handle, source count and affected-variable count; no speculative variable or work survives the preview.
• create_calculated_variable: submit that same definition, current preview handle and an idempotency key. The server rechecks source revisions, consumes the handle and records the mutation, result, audit and isolated recalculation admission atomically. Creation acceptance is not recalculation completion; use the returned operation reference in SanSignal.

Each formula input has a fresh 21-character NanoID slot identifier using letters, digits, _ or -. This identifier is separate from the discovered variable_id or constant_id: refer to the slot as {input:ID} in the expression, keep it unchanged between preview and create, and generate a new slot ID for a different calculation. The server applies the same formula, source, namespace and dependency-cycle rules as the existing calculated-variable editor.

Every mutation requires an idempotency key. Reusing a key with different normalized input is a conflict; replay checks live permissions and maintenance state. The retention window is 24 hours. A preview is bound to the local user, OAuth grant, project, operation, normalized definition and source revisions. It does not prove human approval. After changing a definition or source, obtain a new preview.

Delegated recalculation never merges into another caller’s pending batch. It uses its admitted resource/configuration snapshot and rechecks the grant, token family, user, membership, role, project/organization policy and maintenance state before each candidate-write or publication commit. Revoked, expired or changed authority stops publication; queued work is superseded. Ordinary access-token rotation does not change the admitted user or project. Configuration changes after admission do not expand that work.

For example, after discovering the intended instrument and variable, a six-hour mean query uses query_observations with project_id, instrument_id, one variable_ids entry, explicit UTC start and end, mode: "mean", granularity: "hour" and limit: 100. Supported aggregate modes are mean, median, min and max; granularity is hour, day, month or year. Raw queries have a one-day ceiling; aggregates have a 31-day ceiling. Observation calls select at most 10 variables and return at most 1,000 points. Lists default to 20 items and cap at 100. Requests cap at 256 KiB. Query pages use a roughly 16 KiB target; structured tool results and resource data cap at 60 KiB before the protocol envelope is serialized. Catalog responses have their own shape rather than a universal HTTP size limit.

Hard deletion, archive/restore, source remapping, bulk correction, notification sending, membership/connection administration, key minting and ingestion submission are not MCP tools. Continue to use the appropriate existing dashboard/API workflow for unsupported actions.