MCP tools

← Reference

Monomer offers ten MCP tools. Your client lists them after you sign in and connect it. Read resources to discover their availableOperations, then use monomer_describe to fetch the exact input schema for the operation you need.

Tool	Kind	Use it to	REST operation
monomer_list	Read-only	Discover your Organizations or Workspaces, then browse a chosen target’s collections	POST /v2/agent/list, .../agent/list
monomer_read	Read-only	Inspect a resource, run, or result and the operations it offers	.../agent/read
monomer_search	Read-only	Find Workspace resources by name and description or Pages by display title	.../agent/search
monomer_docs	Read-only	Read these task guides; no Workspace needed	None
monomer_describe	Read-only	Get the exact input schema for advertised operations; no target ID needed	None
monomer_show	Read-only	Show a dashboard draft or session to you as a live view in the chat	None
monomer_check	Read-only	Check an unsaved Semantic Model or Metric definition without saving or contacting a warehouse	.../agent/invoke with action: "check"
monomer_create	Changes data	Create a resource from the task’s input	.../agent/create
monomer_edit	Changes data	Apply a JSON Patch to a Workspace resource	.../agent/edit
monomer_invoke	Changes data	Run an advertised action, such as running a query or applying a dashboard draft	.../agent/invoke, except check

The seven read-only tools have readOnlyHint: true. The three tools that change data have destructiveHint: true, so a client may ask you before it runs them. monomer_invoke also has openWorldHint: true because actions can contact a warehouse. Tools that accept product paths or operation inputs link the Agent API; monomer_docs describes its public documentation paths. Monomer checks your current role on every resource call.

The server’s initialize.instructions provides the shared target-selection and availableOperations discovery flow. Some clients do not pass these instructions to the model, so each tool description also states the part of that flow the tool needs.

Choose a target

Resource calls work on one Organization or Workspace at a time, and the connection does not remember a selection. monomer_docs reads public documentation; monomer_describe reads the fixed contract and takes no Organization or Workspace ID.

• Discovery: call monomer_list with exactly {"path":"workspaces"} or {"path":"organizations"}, with no other fields.
• Workspace resources: pass workspaceId and a path that starts with workspace.
• Organization resources: pass organizationId and a path that starts with organization. Only monomer_list, monomer_read, monomer_create, and monomer_invoke apply.
• Listings: a collection listing under workspace or organization needs limit, an integer from 1 to 100. Continue with the returned nextCursor.

Over REST, the same operations take the target in the URL instead: .../agent/ stands for /v2/workspaces/{workspaceId}/agent/ or, for Organizations, /v2/agent/organizations/{organizationId}/. See Agent API.

Discover an operation’s input

1. Call monomer_list with {"path":"workspaces"} and choose a returned Workspace ID.
2. Call monomer_read with that workspaceId and "path":"workspace". Follow its availableOperations to list a collection or read a resource.
3. For an operation with inputs, copy its entire availableOperations entry into monomer_describe. Problem Details nextActions entries work the same way. Send 1–10 entries in operations, with no target ID.
4. Use the returned tool name and argumentsSchema to construct the complete arguments object for that tool, including the target ID.
5. To continue after a write, inspect result.path: use monomer_read for a resource or monomer_list with limit for a COLLECTION. This gives the current revision and next operations. Resolve names referenced inside definitions with monomer_search, then read the matching resource.

For example, after listing metrics, send the returned create and check entries together to monomer_describe:

monomer_describe input

{
  "operations": [
    {"operation": "CREATE", "path": "workspace/metrics", "inputKind": "METRIC_DEFINITION"},
    {"operation": "INVOKE", "path": "workspace/metrics", "action": "check", "inputKind": "METRIC_CHECK"}
  ]
}

The response is one compact JSON text block. Its operations array follows the input order. For each operation it names the tool and provides argumentsSchema: the complete arguments object to pass to that tool. It preserves the decoder’s exact request properties, descriptions, and any examples, and adds only the required target ID: workspaceId for Workspace paths or organizationId for Organization paths, both UUID strings. Shared definitions appear once and all references resolve inside that response. EDIT entries have no inputKind; their resource path selects the schema. Reuse a schema already fetched for the same operation during the session.

An input-less action also has an argumentsSchema and reports no input; omit input when calling it. You can usually call these actions directly from their advertised entries. A combination outside the contract returns isError: true with a violation locating the invalid entry. Describing an operation does not grant permission or guarantee that a later resource call succeeds.

check entries still say "operation":"INVOKE" in the shared Agent contract. In MCP, call monomer_check for SEMANTIC_MODEL_CHECK or METRIC_CHECK; monomer_invoke rejects them. REST clients use the existing invoke operation and public OpenAPI schema.

Find Pages

Call monomer_search with the chosen Workspace ID. Replace the illustrative ID:

monomer_search input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/pages",
  "queries": ["weekly revenue"],
  "limitPerQuery": 20
}

This Page-only search allows Viewer or higher. Viewer receives currently placed Pages and reader metadata; Explorer or higher can also find unplaced Pages. The same access rules apply in the app. Deleted Pages are excluded. Every whitespace-separated query word must appear in the display title, ignoring case; Page descriptions and Document content are not searched. Read a returned path with monomer_read to inspect the Page.

"path":"workspace" with "kinds":["PAGE"] is also Page-only. The supported kinds are CONNECTOR, CATALOG, SCHEMA, RELATION, SEMANTIC_MODEL, METRIC, DASHBOARD, and PAGE. Other searches require Explorer or higher. Omitting kinds at workspace searches all eight; omitting it at workspace/pages searches Pages only. A mixed search returns ranked metadata matches before Page matches, within the shared limitPerQuery for each query. Search returns one result list per query in input order and has no cursor; use monomer_list for a full collection.

Show a dashboard in chat

In clients that support MCP Apps, such as Claude on the web, monomer_show opens a live, read-only view of a dashboard inside the conversation. Other clients receive a short text result with a link to open the dashboard in Monomer. The view reads data through the same connection and your current role; it saves nothing.

Call monomer_show with the draft path as soon as the draft exists and before editing it: right after the draft start action returns, for a new or an existing dashboard. Call it once per draft. The view follows later edits and finished runs by itself, so do not call it again after every edit. Replace the illustrative IDs:

monomer_show input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/dashboards/0198ef28-2000-7000-8000-000000000101/draft"
}

For a viewer session, pass the variables and queryRuns returned by the session’s resolve or refresh action as selection, and call monomer_show again after a new resolve or refresh.

The view shows the dashboard’s charts, tables and text and keeps updating while it is visible. Inputs, apply and refresh stay in the app or with your agent. Each call adds a new view; older views of the same dashboard stop updating. If your client blocks the code that draws charts, the view offers Open in Monomer instead.

Inputs and results

Tool	Input	Result
monomer_list	AgentListRequest, or the discovery path	AgentResourceListingResponse, or the Organization or Workspace list
monomer_read	Target ID, path, optional download: "arrow"	AgentResourceEnvelope
monomer_search	AgentSearchRequest	AgentSearchResponse
monomer_create	Target ID, path, object input; describe for the exact AgentCreateRequest branch	AgentActionResult
monomer_edit	Target ID, path, array patch, and path-specific revision, commandId, or aggregateMetrics; describe for the exact AgentEditRequest branch	AgentActionResult
monomer_invoke	Target ID, path, action, and input when required; describe for the exact non-check AgentInvokeRequest branch	AgentActionResult
monomer_check	workspaceId, path, action: "check", and check input; describe for the exact check branch	AgentActionResult
monomer_describe	operations: 1–10 verbatim advertised entries	Compact JSON text with tool names and complete argumentsSchema objects
monomer_docs	Optional path of a guide, such as /en/analyze/llms.txt	The guide’s Markdown
monomer_show	workspaceId, a draft or session path, and selection for a session	A short text line with a Monomer link, and the view target in structuredContent

The tool list declares a flat, thin read input with optional download: "arrow", and thin write inputs. Omit download for an ordinary resource read; Arrow download links apply only to Explore result paths. The exact read validation still uses AgentReadRequest, as REST does. The server validates the complete call against the Agent schema, including fields and constraints fetched through describe.

The edit tool declares every accepted top-level argument using the canonical contract: patch and aggregateMetrics are arrays of objects, and commandId is a string. Keep these fields and revision at the top level; do not wrap them in input or send an array as a JSON-encoded string. aggregateMetrics applies only to Semantic Model edits. The tool list declares revision as a decimal string, such as "3": copy it unchanged from the read and never send a JSON number. Send path-specific fields only when the edit’s monomer_describe schema accepts them. That schema determines the required fields, array contents, and constraints for each path. Search also declares its accepted arguments at the top level, including array queries, optional array kinds, and integer limitPerQuery; its complete contract validation remains unchanged.

monomer_describe preserves Pages field descriptions: baseRevision is the Pages tree revision read from the revision field of workspace/pages/tree. commandId is a client-chosen idempotency key; reuse it only for the same command, target and request content, including the revision. Use a new key when changing the request.

Output schemas declare only the required envelope fields below and leave the other fields open. Resource responses still include their full data and the server validates Agent listings, reads, searches, and action results against their owning schemas before returning them.

Response kind	Required output envelope
Read	requestId, kind, path
List	requestId, items, or discovery organizations / workspaces
Search	requestId, results
Create, edit, invoke, check	requestId, operation, path, status, result
Describe, docs	Text only; no outputSchema or structuredContent
Show	requestId, viewContract, workspaceId, dashboardId, title, target, webUrl, shownAt

Action results identify the resulting resource or collection by result.kind and result.path; read or list that reference for its current state. Temporary document uploads return metadata and part URLs directly and have no read or list operation; follow the document upload flow for completion and abort. When a call fails, the result has isError: true and the same Problem Details as REST. Wrong-tool errors start by naming monomer_check or monomer_invoke, whichever accepts the operation. Other write errors start with a hint to use monomer_describe. A failed monomer_docs call returns plain text. Errors in MCP tool calls has the details. Direct your agent shows the discovery flow in a task.