Skip to main content
The MCP server includes tools for querying Omni data and searching the official Omni docs for product and “How do I…”-type questions.

​
Tool availability

To use the MCP server tools, the following settings must be enabled:
  • The top-level MCP server setting in AI Hub > MCP. Enabled by default.
  • The Enable AI and Omni Agent settings in AI Hub > Features. The MCP querying and docs search tools use the same AI pipeline as the Omni Agent, so disabling Omni Agent disables every MCP tool except pickModel and queryUsageAnalytics. The tools will still appear in your MCP client, but calls will return 403 Feature is not enabled errors.
Organization Admins can also individually enable or disable tool capabilities in the MCP settings page. If certain tools are not available in your MCP client, check with an Organization Admin to confirm which capabilities are enabled for your organization.

​
Scoping tool results

MCP tools run with the permissions of a specific Omni user, so results include only what that user can access in Omni. Which user depends on how the MCP client authenticates - for example, if using OAuth, the results are always scoped to the user who completed the OAuth flow. See MCP authentication for more information. With an Organization API key, you can use the X-MCP-User-ID header to run tools as and scope the results to the user specified in the header. Keep the following in mind:
  • The header is only supported for Organization API keys. Requests that use a PAT or OAuth and include the header fail with a 403 error.
  • Not all tools support this header. These tools can’t act as another user, so they fail instead of running as the key’s creator: cancelJob, import-claude-dashboard-from-url, and get-dashboard-import-job-status.
    If a tool honors the X-MCP-User-ID header, it will have an icon next to its name in the following reference sections.
  • A user-scoped key only lists the tools its member can use. With a personal token, an MCP OAuth token, or an embed MCP token, the MCP client lists a tool only if the member holds the permission it needs, on at least one model they can explore.
  • An Organization API key lists every enabled tool regardless of permissions. This includes one using X-MCP-User-ID: the client lists every tool enabled in the MCP settings, even if the impersonated user doesn’t have permission to use it. Calls to those tools can still fail.
  • A pinned model narrows which model’s permissions count. If the connection sets X-MCP-Model-ID, tools that run on a model check the member’s permissions on that pinned model only, not on any model they can explore.
  • A lowered role can leave a personal API key with no tools. If the member’s role drops below Restricted Querier after the key was created, the key gets no tools at all.
  • Embed users must have an active embed session. If the header specifies an embed user without an active session, app tools fail with a 403 error.
  • A connection with no available tools still gets an empty list. The MCP client receives an empty tool list.

​
Querying

Tools used to process queries received by the MCP server.
This tool is always available.
Returns a list of available models and their IDs, which the MCP client uses to select which model to query. You can also provide a model ID in the MCP configuration to skip this step.If you have access to only one model, getData, pickTopic, askOmni, and listBranches use it automatically — you don’t need to call pickModel or pin a model with the X-MCP-Model-ID header.This tool is still useful when you have access to more than one model. In that case, those tools return an error listing the available models and naming the X-MCP-Model-ID header, so you can choose one.
This tool is always available.
Returns available topics in the model selected by pickModel and selects the most relevant topic for the query.If the AI is allowed to query any view in the model (enabled with the X-MCP-Query-All-Views header during setup), this step becomes optional: the AI can query any view in the model directly, not just topics.
This tool is always available.Additionally, this parameter isn’t supported for embed.
Executes the query against the selected model and topic — or view, if querying outside of topics is enabled with the X-MCP-Query-All-Views header during setup — and returns the results.Optionally pass requestedLlm to generate the query with a specific LLM instead of the organization default. Your selection lasts for one call. If you select an LLM you can’t use, you’ll receive an error. Use listLlms to list the LLMs you can pick.If your organization is over its AI credit threshold, the result includes downgradedLlm, naming the LLM the query ran on instead of your usual one.
This tool is always available.
Executes a pre-built JSON query definition directly against the Run query API. Use this tool when the query JSON is already known. For example, you pasted a query definition in the chat, or the query definition was produced earlier in the conversation.Optionally pass branchId to run the query against that model branch instead of the base model.When using this tool, note that:
  • Results default to a limit of 500 rows and cap at 10,000
  • Keys such as userEditedSQL that would cause the query to run raw SQL against the connection will be refused
  • If a model is provided with the X-MCP-Topic-Name header during setup and query.modelId is also provided, they must match or the request will fail
This tool is always available.
Lists the LLMs the user may pass as requestedLlm to askOmni or getData.

​
Advanced agentic queries

The Agentic capabilities setting must be enabled to use the tools in this section.
Tools used to process complex, multi-step questions that require deeper analysis beyond what a single query can provide.
Submits an agentic analysis job to Omni and waits up to 20 seconds for it to progress before returning, so a short job can often finish and return its answer in a single call. This tool is designed for open-ended questions that may require multiple steps, data exploration, or iterative analysis.If the job finishes within that window, askOmni returns the completed result and includes a jobId. If it hasn’t finished yet, askOmni returns a running result with the job’s current step and includes a conversationId. Pass the jobId to checkStatus to keep polling it. Pass waitSeconds to change how long askOmni waits before returning; 0 returns immediately with the submitted job. If you disconnect from Omni while askOmni is waiting, the job is cancelled.
If your MCP client’s host supports the MCP Tasks extension (io.modelcontextprotocol/tasks), askOmni instead returns at once as a task, and the host polls the job on its own — your MCP client doesn’t make any checkStatus calls. Today, only Claude Code (terminal and Agent SDK sessions) supports this, in public beta behind an Anthropic rollout flag. Claude Desktop and the VS Code extension don’t support it yet, so those clients have the wait-then-poll behavior described above.
When a branchId is provided, the agentic job runs its queries against that model branch and any model edits the agent makes are saved to that branch rather than creating a new one.Optionally pass requestedLlm ({ provider, model, thinking? }) to run the job on a specific LLM instead of the organization default — use listLlms to find the LLMs you may pick. A pick you may not use is refused with an error that names only that LLM; embedded users can’t use this parameter.This tool can also:
  • Create and edit dashboards: When you ask the agent to edit an existing dashboard, the changes land in a draft. The changes won’t be live until you review and manually publish the changes. Brand-new dashboards created by the agent are published immediately.
  • Create, find, and run routines:
    • To create a routine: Ask for something recurring (“every Monday at 9am, email me a summary of last week’s signups”) and the agent sets up a scheduled prompt that runs with your permissions and delivers by email or Slack.
    • To find a routine: Find or list your existing routines (“what do I have scheduled?”) and the agent returns matches as edit links.
    • To run a routine: Ask to run an existing routine by name (“run the Weekly signups routine now”) and the agent starts the run immediately, delivering results to you and the routine’s configured recipients.
  • Create, edit, run, and delete skills:
    • To create or edit a skill: Ask the agent to save a way of working as a skill, or to change an existing one by its /identifier (“change /weekly-report to group by region”).
    • To run a saved skill: Type a skill’s /identifier anywhere in the prompt and the agent runs it, resolved as the effective user — impersonated with the X-MCP-User-ID header, or the key’s owner otherwise.
    • To delete a skill: Ask for a skill to be deleted (“delete /weekly-report”) and the agent deletes it immediately when the request clearly names it. If it’s unclear which skill you mean, or whether you want it deleted, the agent asks a follow-up question instead of deleting anything.
Pair with checkStatus only when a job outlasts askOmni’s wait time. A job that finishes within the window never needs it, and an MCP client whose host supports MCP Tasks doesn’t need it at all.
Checks the status of a previously submitted job using its jobId. By default, checkStatus waits (long-polls) up to 20 seconds for the job’s step to change or for the job to reach a terminal state, instead of returning immediately.Pass waitSeconds to change how long to wait before returning. It defaults to, and is capped at, 20 seconds; 0 returns immediately with the job’s current status.Pass lastStep with the progress.message you last saw to return as soon as the job’s step has moved past it, even before the wait would otherwise end.Progress may also include a toolName naming the tool behind the current step, such as generate_query.Stopping checkStatus polling does not stop the job — use cancelJob to stop it.
Stops a job started by askOmni, using its jobId. The job is marked cancelled right away, but the agent stops when it next checks, so a query or an edit it already started can still complete after the call returns.The tool reports the job’s outcome as a status:
  • cancelled — The job was stopped
  • too_late — The job had already moved on to delivering its result and could not be stopped
  • complete or failed — The job had already reached that outcome before the call
Lists existing branches of a given base model. Use this tool alongside askOmni’s or runQuery’s branchId parameter to target an existing branch instead of creating a new one.
The Skills and Chat settings in AI Hub > Features must be enabled and the calling user must have AI access to use this tool.
Finds a saved skill by name, identifier, or description and reads its instructions. This tool does not run a skill.If you’re an Organization Admin, all skills in the organization will be returned; otherwise, only skills you created will be returned.
Records a thumbs up or thumbs down and an optional comment on an askOmni answer, using its jobId. Organization Admins can view responses on the AI Hub > Quality > User feedback dashboard.

​
Content access

The Content access setting must be enabled to use the tools in this section.
Tools used to search your organization’s saved content, see the queries a document contains, and run them.
Searches your Omni organization for existing dashboards and apps that match a provided name, folder, or tile name. This helps prevent generating new queries for data that already exists in a saved dashboard or app.
Lists the saved queries in a document, such as a workbook or app. This tool is designed to pair with searchContent — search finds the document; this tool shows the queries it contains.Each query’s response also includes the field names it selects (fields) and already filters on (filterFields), so you can copy the exact field names a runSavedQuery filter override needs to target. When set on the query, the response also includes description and subTitle, so you can tell near-identical queries apart instead of guessing from their names alone.
Executes a saved query by ID and returns the current results as JSON. This tool is designed for pulling consistent, model-aware data from a known query rather than generating a new query.An optional filters object, keyed by field name, replaces the saved filter on each named field for that run only; the saved query itself is never changed. Use listDocumentQueries to get the field names a filter can target.If an invalid or inaccessible queryId is provided, the tool returns an error without listing tile names to prevent information disclosure beyond impersonation scope. Use listDocumentQueries to retrieve valid queryId values for a document.
Starts an asynchronous job to download a dashboard as a PNG or paged PDF file, using the Initiate dashboard download API. The tool accepts a dashboard identifier and an optional format (png by default, or pdf). A PDF is rendered as letter-size, landscape pages, which keeps large dashboards readable in cases where a PNG render would be too large.Only one download job can run per user per dashboard at a time. If a download for the user is already in progress, the tool returns an error that names the existing job’s ID and points to checkDashboardDownload and fetchDashboardDownload.
Polls the status of a dashboard download job started by startDashboardDownload, using its jobId.
Retrieves the finished PNG or paged PDF file for a completed dashboard download job, using its jobId.A PDF is returned as an MCP embedded resource. PNG files larger than 10 MB and PDF files larger than 30 MB are refused. When this happens, the tool explains how to download the file directly from the dashboard in Omni instead.An optional element argument fetches one chart’s own PNG capture, named by its queryIdentifierMapKey, instead of the whole file. Only a job whose render captured individual chart images has these. If the job doesn’t have a capture under the requested name, the tool returns an error naming the elements it does have, or saying it has none.

​
Apps

The Content access setting must be enabled to use the tools in this section. putApp, patchApp, and publishDraft also require Agentic capabilities to be enabled.
Tools used to read, write, publish, and render apps. Changes made with putApp or patchApp land on the document’s shared main draft and are invisible to other viewers until publishDraft runs. The recommended flow is to read the draft with getAppDraft, falling back to getApp only when no draft exists yet, then write, then publish. App settings cannot be changed using these tools. Use the Omni UI to modify app settings.
Reads a published app document’s complete HTML source and sandbox settings, given a document identifier. Draft edits are not included in the response; use getAppDraft instead. Very large apps may not be retrievable, since the returned HTML has a size cap.
Reads the main draft’s app HTML and settings.
Replaces the app’s HTML on the document’s shared main draft. The draft is created automatically on the first write and reused on subsequent writes.
Applies htmlEdits to the app on the document’s shared main draft, instead of replacing the whole HTML.Like putApp, the draft is created automatically on the first write and reused on subsequent writes.
Publishing a draft publishes all the changes it contains, including any other editors’ unpublished changes to the same document.
Publishes the main draft so its changes become visible to viewers. Before publishing, this tool reads the draft to confirm it contains an app and refuses if it doesn’t.
Some MCP clients may not render apps correctly. Omni has confirmed that Claude Desktop, ChatGPT, and VS Code with Copilot correctly render apps. Cursor can render apps, but you may need to open a widget to view the app instead of the app opening by default.
Renders a saved, interactive app inline with live data.An app rendered through MCP runs under the same sandboxing and governed queries as everywhere else in Omni. See Apps security for more information.

​
Claude Dashboard import

The Agentic capabilities and Enable apps settings must be enabled to use the tools in this section.
Tools used to rebuild Claude Dashboards exported to Omni as apps. See Importing Claude dashboards as apps for more information. With a personal token or MCP OAuth connection, these tools register only when the member holds Use Omni Agent, Create apps, and Write SQL (Querier) together on one model, and isn’t an embed user. See the Requirements section for more information.
Fetches the dashboard file Claude sends and starts a job that rebuilds it as an Omni app over the connected model. Returns a job_id to poll with get-dashboard-import-job-status.The tool picks the model to extend from model_id, or the connection’s X-MCP-Model-ID header if one is set.If neither is provided, the tool uses the one model the key has access to. If there are several models, the tool returns an error listing the models — currently, a model can’t be automatically selected. An error is also returned if there aren’t any accessible models.
Only send dashboards once. Each time a dashboard is sent, it creates a new Omni app. Apps from earlier sends aren’t updated.
Polls an import job using the job_id returned by import-claude-dashboard-from-url.Returns processing with the current phase, done with the app’s dashboard_url (and review_url, when available), or failed with the reason.

​
Search Omni docs (searchOmniDocs)

The Omni documentation search setting must be enabled to use this tool.
Searches the Omni documentation and synthesizes answers in response to prompts that ask questions about how to use Omni. Responses include citations to documentation pages used to construct the answer to the prompt. This tool uses the same AI-powered search pipeline as the Omni Agent, ensuring accurate and contextually relevant responses. For example, you could ask “How do I create a calculated field in Omni?” and the searchOmniDocs tool will search the documentation, analyze the relevant pages, and return a comprehensive answer with links to the source documentation.

​
Usage analytics (queryUsageAnalytics)

To use this tool:
  • The Usage analytics setting in AI Hub > Features must be on. There is no toggle for this tool in MCP settings.
  • You must be an Organization Admin.
Answers questions about how your organization uses Omni, such as activity, adoption, and AI usage. Only Organization Admins can use this tool. The tool uses read-only queries on your organization’s usage data. For example, you could ask:
  • “Show me AI credit usage by user for the last 30 days.”
  • “Use the usage analytics tool, look at the schedules dashboard, pull up recent failures.”
  • “Which pieces of content have not been used in the last 30 days? I’d like a link to the dashboard, when it was last viewed, and the name of the creator.”
  • “With the usage analytics tool, identify the slowest topics. Analyze them and suggest improvements I can potentially make to them.”
To explore further, open Analytics in your organization. This tool is rate-limited per admin. If a client hits the limit, the call returns an error; wait a few minutes and try again. With a PAT or OAuth, the tool appears in your MCP client only if you’re an Organization Admin. With an Organization API key, the tool appears for everyone, but calls fail for members who aren’t Organization Admins. If an Organization API key uses the X-MCP-User-ID header to act as another member, the tool checks whether that member is an Organization Admin. If the member ID doesn’t exist, the tool returns a not-found error.

​
Tool and setting comparison

The following table shows which MCP tools are available if a specific MCP setting is enabled.
A icon indicates that additional settings must be enabled to use a tool — hover over the icon to view the names of the additional settings.
queryUsageAnalytics isn’t controlled by an MCP setting. It’s controlled by the Usage analytics AI feature setting and is available to Organization Admins only.
  • Skills - Build reusable, AI-powered processes that your team can trigger with a single click or mention
  • AI MCP settings - Enable and disable MCP server tool capabilities
  • AI feature settings - Enable and disable individual AI features in your Omni organization
  • AI Hub - Monitor how your organization uses Omni AI