The Model Context Protocol (MCP) lets external AI assistants — Claude, ChatGPT, OpenAI Codex, and custom agents — connect to Qyra and query your data directly. Qyra runs the MCP server and your assistant is the client, so it can explore your data models, search for metrics and dimensions, run queries, and surface data-driven insights through natural conversation. MCP uses secure OAuth authentication and respects all your existing access controls, so data stays protected.

With MCP, your AI assistant becomes a data analyst that can:

• Browse and understand your data models
• Find relevant metrics and dimensions
• Run queries and generate visualizations
• Discover existing charts and dashboards, including verified content
• Create and edit charts and dashboards using content-as-code
• Leverage your AI agents' domain expertise and verified answers
• Switch between different projects seamlessly
• Respect your data governance and access controls

Get started

Setting up MCP is quick and straightforward. You can connect your AI assistant to your Qyra instance in just a few minutes.

Prerequisites

• A Qyra Cloud account or Enterprise account with MCP enabled
• An MCP-compatible AI assistant (e.g., Claude.ai, Claude Desktop, ChatGPT, OpenAI Codex)

Find your instance name

Your instance name is the subdomain of the URL you use to open Qyra in your browser. Open Qyra, look at the address bar, and take the part before .qyraflow.com:

If you self-host Qyra on your own domain, the MCP endpoint lives at https://<your-qyra-host>/api/v1/mcp instead. See MCP for self-hosted instances.

Network requirements

If your organization uses a corporate firewall, VPN, or internet security tool, the following domains must be allowlisted for MCP to work correctly:

If you're having trouble, try opening Claude in an incognito or private browser window to rule out browser extensions such as ad blockers that may be blocking these domains.

Installation

Claude.ai (Web & Desktop Apps)

Set up MCP in the Claude.ai web app, and it will automatically sync to your Claude Desktop app after restart.

ChatGPT (Web App)

ChatGPT support for MCP is coming soon! Stay tuned for updates.

OpenAI Codex

Claude Code CLI

For developers using Claude Code CLI:

claude mcp add qyra https://<your_instance_name>.qyraflow.com/api/v1/mcp -t http

Replace <your_instance_name> with your actual Qyra instance name (commonly app or eu1, see Find your instance name).

Cursor Editor

Navigate to Cursor Settings > MCP & Integrations

Custom Integration (For Developers)

If you're building your own agents or automated workflows, you can integrate directly with Qyra MCP:

• Transport: Qyra MCP exposes a StreamableHTTP transport endpoint at https://<your_instance_name>.qyraflow.com/api/v1/mcp
• Debugging: Use @modelcontextprotocol/inspector to inspect and debug the MCP connection
• Authentication: For interactive setups use OAuth 2.0. For headless agents and automated workflows, you can authenticate with a Personal Access Token by passing it in the Authorization header — both Authorization: ApiKey ldpat_<redacted> and Authorization: Bearer ldpat_<redacted> are accepted on the MCP endpoint and resolve to the same PAT authentication path. The Bearer alias is accepted only on the MCP endpoint. Use Bearer when your MCP host only supports static Bearer tokens (for example, Claude managed agents and other third-party MCP hosts that don't let you choose a custom auth scheme); use ApiKey for direct HTTP clients where you can set the scheme yourself, since it makes it explicit that the token is a Qyra PAT. Create the token under Settings → Personal access tokens for the user whose permissions and attributes you want the integration to use. Service account tokens are also supported on plans that include them.
• Documentation: See the MCP specification for implementation details
• Pin a project (optional): pass X-Qyra-Project: <project-uuid> to scope the MCP session to a specific project, skipping the set_project step. See details below.
• Override user attributes per request (optional): pass X-Qyra-User-Attributes: <json> to override the authenticated user's attributes for that request (useful for row-level security when an agent acts on behalf of different end-users). See details below.

Pin a project with the X-Qyra-Project header

By default, MCP clients use set_project to choose an active project, and the selection is stored as a per-user context. If you're building an integration that should always operate against a single project, you can pre-select the project by sending the X-Qyra-Project header on every request to /api/v1/mcp.

When the header is set:

• The project UUID in the header is used as the active project for that request, overriding any project previously set with set_project.
• The list_projects and set_project tools are hidden from tools/list, so the AI assistant can't change the project for the request.
• Access to the project is still enforced by your user, API key, or service account's permissions — the header can't be used to access projects the caller can't already see.

This is useful when you want each integration, workspace, or environment to be locked to one project (for example, a separate connector per project) without relying on the AI assistant to call set_project first.

The header value must be a valid project UUID. You can find the project UUID in the Qyra URL when viewing a project (/projects/<projectUuid>/...).

{
  "mcpServers": {
    "qyra-sales": {
      "url": "https://<your_instance_name>.qyraflow.com/api/v1/mcp",
      "headers": {
        "X-Qyra-Project": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

curl https://<your_instance_name>.qyraflow.com/api/v1/mcp \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Qyra-Project: 00000000-0000-0000-0000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Override user attributes with the X-Qyra-User-Attributes header

The X-Qyra-User-Attributes header overrides the authenticated user's Qyra user attributes for that specific MCP request. This is designed for agents that act on behalf of multiple end-users with row-level security: one PAT (or service account) user handles all requests, and per-request RLS scoping is applied via the header.

The header value must be a JSON object where each value is either a string or an array of strings. For example:

• {"user_id": "abc123"}
• {"user_id": ["abc123", "def456"]}

curl https://<your_instance_name>.qyraflow.com/api/v1/mcp \
  -H 'Authorization: ApiKey <your_token>' \
  -H 'X-Qyra-User-Attributes: {"user_id": "abc123"}' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

{
  "mcpServers": {
    "qyra-agent": {
      "url": "https://<your_instance_name>.qyraflow.com/api/v1/mcp",
      "headers": {
        "X-Qyra-User-Attributes": "{"user_id": "abc123"}"
      }
    }
  }
}

What it can do

Core capabilities

MCP provides AI assistants with powerful tools to interact with your Qyra data:

Project management

• List projects - View all accessible projects in your organization
• Set active project - Switch context between different projects (required before accessing any data). Accepts an optional tags array to filter the explores and fields visible in the session to those matching the given tags — the same tag-based filtering used by AI agents, but available directly in an MCP session without needing an agent. Useful when tags work in the Qyra UI but you also want to scope an MCP session to a specific domain (e.g., ["sales"]).
• Get current project - Check which project is currently active

Data exploration

• List explores - See all available data models in the current project at a glance
• Find explores - Search for relevant data models using natural language (e.g., "customer orders")
• Find fields - Search for specific metrics and dimensions by business terms (e.g., "total revenue", "order date")
• Search field values - Look up valid values for a field, useful for building filters
• Find content - Search for existing spaces, charts, and dashboards by name or description. Results include space breadcrumbs and direct links. Optionally scope the search to a single space (and its descendants) by passing a space slug.
• List content - Browse accessible content as a hierarchy. By default it returns root-level spaces; pass a space slug to list the charts, dashboards, and nested spaces directly inside that space. Use this when you want the agent to walk space → content rather than search by keyword.
• List verified content - Discover charts and dashboards that admins have marked as verified, so agents can reference trusted, canonical patterns when building new content. If you want your agent to prefer verified patterns, ask it to in your prompt (e.g. "Use verified charts as the reference for any new chart you build.").

Query execution

• Run metric query - Execute queries using your semantic layer's metrics and dimensions. Completed results include a best-effort exploreUrl so you can open the query in Qyra to keep exploring.
• Render chart - Render a visualization (tables, bar charts, line charts, pie charts, and more) for a completed metric query result in MCP App-capable clients (e.g., Claude). Call this after a metric query finishes when you want a visual chart; the query is not re-executed. SQL Runner results are not supported by render_chart.
• Run SQL - Execute arbitrary SQL queries directly against the project's data warehouse. Useful for ad-hoc analysis or queries that don't fit the explore-based model. Returns up to 500 rows by default (configurable up to 5,000). Completed results include a best-effort sqlRunnerUrl so you can open the compiled SQL in SQL Runner.
• Get query result - Poll for the result of a long-running query. If run_metric_query or run_sql doesn't finish within its wait window, the tool returns a queryUuid and the assistant polls get_query_result until the warehouse completes the query — so long queries don't time out the session.

Editing content

MCP can read, create, and edit Qyra charts and dashboards using the same content-as-code payloads that the Qyra CLI uses. This lets agents make targeted edits to existing content or build new charts and dashboards directly in a conversation, without downloading YAML files locally.

• Read content (read_content) - Fetch a chart or dashboard as JSON by slug. Call this before editing so the agent can see the current state.
• Edit content (edit_content) - Apply an RFC 6902 JSON Patch to an existing chart or dashboard, then validate and persist. Use this for surgical changes (e.g. rename a field, add a filter, swap a chart color) without rewriting the whole object.
• Create content (create_content) - Create a new chart or dashboard from a full chart-as-code or dashboard-as-code object. Returns the persisted slug and URL.

These tools reuse the same permissions, validation, and project context as the Qyra CLI download and upload commands, so the user driving the MCP session needs the same access required to manage that content in Qyra.

Editing the dbt project

MCP exposes AI writeback — editing the dbt project that backs the active Qyra project and opening a pull request with the change — to any MCP client. Ask the assistant to rename a metric, add a dimension, edit a model's SQL, or fix a YAML description; the assistant calls the tools below and hands back a pull request URL when the run finishes. The AI writeback prerequisites — supported git host, app installation, project Developer permission — apply to the MCP surface too.

• Run AI writeback (run_ai_writeback) - Start a writeback run against the active project's dbt repository from a natural-language prompt. The target GitHub or GitLab repository and dbt sub-folder are resolved server-side from the project's dbt connection — you don't specify them. Returns immediately with an aiWritebackRunUuid.
• Get AI writeback status (get_ai_writeback_status) - Poll a writeback run by id. Returns the current pipeline stage while the run is in flight, and the pull request URL (or an error message) once it reaches a terminal state.

How the async flow works

A writeback run typically takes a few minutes — longer than most MCP transports will hold a connection open — so run_ai_writeback enqueues the run to a background worker and returns immediately with a run id. The caller then polls get_ai_writeback_status for the outcome. See How it works for what the run itself does.

Polling has no session affinity — you can call get_ai_writeback_status from a different MCP session or a different API token, as long as the caller has view access to the project the run belongs to. This makes the pair usable from short-lived automations and shell scripts, not just interactive chat clients.

run_ai_writeback — start a run

Parameters

• prompt (string, required) — A clear, self-contained description of the change to make to the dbt project (for example, "Add a total_revenue metric to the orders model as the sum of amount"). When the project has more than one dbt source, name the intended source in the prompt itself (for example, "In the marketing dbt project, ...") — the run reports the available sources back through get_ai_writeback_status if it can't tell which one you meant.

Response (structuredContent)

{
  "aiWritebackRunUuid": "b3f4e0e2-8a2b-4d5f-9a1f-1c2d3e4f5a6b"
}

get_ai_writeback_status — poll for the result

Parameters

• aiWritebackRunUuid (UUID, required) — The id returned by run_ai_writeback.

Response (structuredContent)

{
  "status": "ready",
  "prUrl": "https://github.com/acme-analytics/jaffle-shop/pull/482",
  "errorMessage": null
}

• status is either "pending" (not yet picked up by a worker), an in-progress pipeline stage (for example, "sandbox", "agent", or "pull_request"), or a terminal value: "ready" (finished — check prUrl) or "error" (finished — check errorMessage).
• prUrl is set once status is "ready" and the agent changed at least one file. If the agent decided no change was needed, status is still "ready" but prUrl is null.
• errorMessage is set once status is "error". This also covers the "more than one dbt source" case — the message lists the available sources so the caller can re-run run_ai_writeback naming the intended one in the prompt.

Poll every 10-15 seconds rather than tight-looping — a run typically takes a few minutes to finish, and the status row updates in stages rather than continuously.

Example poll loop

const { aiWritebackRunUuid } = (
  await callMcpTool('run_ai_writeback', {
    prompt: 'Add a total_revenue metric to the orders model as the sum of amount.',
  })
).structuredContent;

while (true) {
  const { status, prUrl, errorMessage } = (
    await callMcpTool('get_ai_writeback_status', { aiWritebackRunUuid })
  ).structuredContent;

  if (status === 'ready') {
    console.log(prUrl ? `PR opened: ${prUrl}` : 'No file changes were needed.');
    break;
  }
  if (status === 'error') {
    throw new Error(errorMessage ?? 'Writeback failed');
  }

  await new Promise((r) => setTimeout(r, 10_000));
}

When prompting an agent to build content, ask it to use verified content as a reference. The agent can call find_content and read_content on a verified chart, then use that JSON as the template for create_content, so what it saves follows the patterns your team has already approved.

Example prompt: "Read the weekly-revenue chart, then create a copy called weekly-revenue-by-region that adds customers_region as a pivot dimension."

The assistant will call read_content to fetch the source chart, modify the JSON to add the pivot, and call create_content to save the new chart — returning a link to open it in Qyra.

Scheduled deliveries

• Create scheduled delivery (create_scheduled_delivery) - Schedule an existing chart or dashboard to Slack, email, or another supported destination on a cron schedule. Point the tool at the content by slug and pass the schedule and recipients — the delivery is created against the active project using the caller's permissions.

Example prompt: "Set up a scheduled delivery of the weekly-ecom-orders chart to #analytics-updates in Slack every Monday at 9am."

The assistant will call create_scheduled_delivery with the chart's slug, the cron schedule, and the Slack destination — mirroring the AI agent createScheduledDelivery tool but exposed to any MCP client.

Agent context

• Route agent - Automatically select and activate the best agent for a user prompt within the active project. This is the preferred way to pick an agent — it mirrors the AI Router experience in the Qyra app, so MCP sessions get the same automatic agent selection.
• List agents - Discover available AI agents and their areas of expertise
• Set agent - Manually activate an agent to scope your session to its explores, instructions, and verified answers. Use this when you want to override automatic routing.
• Get current agent - Check which agent is active and view its full context
• Clear agent - Remove agent scoping and return to the full project context

These tools are covered in detail in the Using AI agent context section below.

Built-in skills

Qyra ships built-in skills (such as developing-in-qyra) that give AI assistants guidance for working with Qyra — for example, conventions for writing dbt models, charts, and dashboards. These skills are exposed as MCP resources, which most clients consume automatically.

For MCP clients that don't read resources directly (e.g. Claude Code), three fallback tools let the assistant discover and load the same content:

• List skills (list_skills) - Return the available built-in skills along with their supporting resource files
• Read skill (read_skill) - Read the main SKILL.md instructions for a skill by name (e.g. developing-in-qyra)
• Read skill resource (read_skill_resource) - Read a supporting resource file for a skill by name and resource path (e.g. resources/dashboard-best-practices.md)

You don't need to call these tools explicitly — when relevant, the assistant will call list_skills to discover what's available and then load the skill content it needs. If your client already supports MCP resources, you can ignore these tools; both paths return the same content.

Example conversations

Here are some examples of how you can interact with AI assistants using MCP:

Example 1: Verifying your MCP connection

After connecting, verify that the MCP integration is working by asking your AI assistant to list available tools.

Prompt: "What Qyra tools do you have access to?"

The assistant will confirm the connection and list the available MCP tools, such as list_projects, find_fields, run_metric_query, run_sql, and others. This is a quick way to verify that authentication succeeded and the MCP server is reachable.

Example 2: Setting up a project and finding dashboards

Before querying data, you need to set an active project. Then you can search for existing dashboards and charts.

Prompt: "What projects do I have access to? Set the Jaffle Shop project, then show me all dashboards related to revenue."

The assistant will:

1. Call list_projects to show your available projects
2. Call set_project to activate "Jaffle Shop"
3. Call find_content with your search term to find matching dashboards and charts

Expected output: A list of dashboards and charts matching "revenue", including their names, descriptions, and direct links to view them in Qyra.

Example 3: Exploring data and running a metric query

Once a project is active, you can explore data models and run queries using your semantic layer.

Prompt: "What metrics do we have for orders? Show me total revenue by month for the last 6 months as a bar chart."

The assistant will:

1. Call find_fields to search for order-related metrics and dimensions (e.g., orders_total_revenue, orders_order_date)
2. Call run_metric_query with the appropriate explore, metrics, dimensions, filters, and sort order to fetch the data and render a visualization

Expected output: A bar chart showing monthly revenue for the last 6 months, along with the underlying data table. The query uses your semantic layer definitions, so metric calculations and joins are handled automatically.

Using AI agent context

If your organization has Qyra AI agents configured, you can reuse their configuration in your MCP sessions — so you get consistent guidance regardless of where you're working.

How is this different from Qyra AI agents?

Qyra AI agents are a fully managed experience inside Qyra and Slack. They handle everything end-to-end: interpreting your question, picking the right data, running queries, and presenting results.

With MCP, you can use Qyra data in other contexts, but the AI assistant driving an MCP session doesn't have the same specialized tuning that Qyra AI agents provide out of the box. Agent context via MCP bridges that gap: it brings your agents' domain knowledge into any MCP session.

What you get from agent context

When you activate an agent in your MCP session, your AI assistant receives:

• Specialized content: only the data models relevant to that agent's domain
• Verified answers: curated example queries that demonstrate correct usage of the data model
• Custom instructions: domain-specific rules like "Always filter orders by status = 'completed'"

Example workflow

1. Set your project with set_project
2. Let the router pick an agent with route_agent — pass the user's prompt and Qyra activates the best-fit agent automatically. Use list_agents + set_agent only when you want to inspect candidates or override the choice manually.
3. Ask your questions — the agent's context automatically guides queries

Prompt: "What AI agents are available?"

Prompt: "Use the Sales Analyst agent."

Once an agent is active, your queries automatically follow its instructions. For example, with a Sales Analyst agent configured with these instructions:

You are a Sales analyst for Jaffle Shop. Your role is to answer questions
about revenue, orders, customers and subscriptions.

Key guidelines:
- Use the orders explore as the starting point for revenue and order
  volume questions.
- Always include a time dimension when showing trends. Default to monthly
  granularity unless the user specifies otherwise.
- Format currency values in CAD.

Prompt: "Can you show me revenue so far?"

The assistant will automatically use the orders explore, include a monthly time dimension, and format values in CAD — all without you specifying these details, because the agent's instructions guide the query.

Built-in prompt

The Qyra MCP server includes a built-in qyra-analyst prompt with guidelines for querying data effectively. MCP clients that support prompts can use this automatically, so you don't need to configure custom instructions manually.

Best practices

To get the most value from MCP, ensure your Qyra data is well-organized and documented. See our Effective analytics with agents for detailed recommendations on:

• Organizing and naming your data models
• Writing effective documentation and AI hints
• Optimizing for AI assistant performance
• Security and permissions considerations

Qyra Docs MCP

In addition to the Qyra data MCP above, we also offer a Docs MCP endpoint that gives AI coding agents access to the complete Qyra documentation. This is free for everyone—including open source users and all cloud tiers.

Benefits

The Docs MCP helps AI agents:

• Understand Qyra concepts, configuration, and best practices
• Generate accurate YAML configurations for metrics and dimensions
• Troubleshoot issues using official documentation
• Stay up-to-date with the latest Qyra features

Setup

The Docs MCP endpoint is available at https://docs.qyraflow.com/mcp. Add it to your AI coding tool:

{
  "mcpServers": {
    "qyra-docs": {
      "url": "https://docs.qyraflow.com/mcp"
    }
  }
}

Availability

The Docs MCP is free for everyone:

• Open source users
• Cloud Pro
• Cloud Enterprise

No authentication required.

FAQ

Q: Does Qyra MCP store my data or query results?

A: No, Qyra MCP does not store any query results, conversation responses, or data. MCP acts as a bridge that allows AI assistants to access your Qyra metadata and execute queries in real-time. The MCP consumer (your AI assistant) is responsible for any data storage. Depending on which AI assistant you use, data might be shared with third parties according to their privacy policies.

Q: Can multiple team members use MCP?

A: Yes, each team member can set up their own MCP connection with their individual Qyra credentials. Each connection respects that user's specific permissions and access controls.

Q: Can MCP modify my data or dashboards?

A: MCP can create and edit Qyra charts and dashboards via the content-as-code tools, and can create scheduled deliveries, when your user account has the required permissions. MCP cannot modify your underlying warehouse data — query execution is read-only (metric queries and SQL SELECT only). All write operations respect your existing Qyra permissions and project access controls, and each write tool is only registered for users whose role grants the corresponding scope.

Q: Claude returns data as text but no visual chart is displayed. What's wrong?

A: Claude uses the domain claudemcpcontent.com to render visual content from MCP connectors. If this domain is blocked by your corporate firewall, VPN, internet security tool, or a browser extension (like an ad blocker), Claude will fall back to text-only output. See Network requirements above for the full list of domains to allowlist.