> For the complete documentation index, see [llms.txt](https://docs.darcyiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.darcyiq.com/core-features/apps.md).

# Apps

Build custom dashboard pages powered by MCP UI artifacts with DarcyIQ's Apps feature. **Create interactive, widget-based app pages that surface real-time data, tools, and visualizations** directly in your DarcyIQ navigation — perfect for operational dashboards, monitoring panels, and custom tooling.

{% hint style="success" %}
**From MCP to Dashboard in Minutes**: Turn any MCP UI artifact into a live dashboard widget, arrange multiple widgets on a single page, and share the app with your team.
{% endhint %}

## Overview

Apps let you compose one or more MCP UI artifacts into dedicated pages that appear in your DarcyIQ sidebar, giving your team instant access to the tools and data they need.

| Feature               | Capability                                      | Business Impact                               |
| --------------------- | ----------------------------------------------- | --------------------------------------------- |
| **Custom Pages**      | Create dedicated app pages in your navigation   | One-click access to key tools and data        |
| **Widget Dashboards** | Arrange multiple artifacts in a responsive grid | Unified view of related information           |
| **Flexible Layouts**  | Full, Half, and Third-width widget sizing       | Tailor the layout to your content             |
| **Drag-and-Drop**     | Reorder widgets visually                        | Prioritize what matters most                  |
| **Team Sharing**      | Share apps with configurable permissions        | Consistent dashboards across the organization |
| **Enable / Disable**  | Toggle app visibility without deleting          | Control what appears in the navigation        |

## Creating an App

{% stepper %}
{% step %}
**Open Apps** Navigate to the **Apps** section from the sidebar, then click **Create App**.
{% endstep %}

{% step %}
**Provide Details** Enter a name for your app, an optional description, and choose an icon from the built-in icon library.
{% endstep %}

{% step %}
**Select Your First Widget** Choose an MCP UI artifact from your artifact library. This becomes the initial widget displayed on the app page.
{% endstep %}

{% step %}
**Enable the App** Toggle the **Enable App** switch to make the app visible in the navigation menu. You can also leave it disabled while you build it out.
{% endstep %}

{% step %}
**Save and Customize** After creating the app, expand it in the list to add more widgets, adjust layouts, and reorder content.
{% endstep %}
{% endstepper %}

## Dashboard Widgets

Each app page is composed of one or more **widgets**, where each widget displays an MCP UI artifact. Widgets are arranged in a responsive 12-column grid.

### Adding Widgets

1. Find your app in the Apps list and click to expand it
2. Click **Add Widget**
3. Select an MCP UI artifact from the artifact library
4. The widget is added to the dashboard

### Widget Layout Options

Each widget can be sized to fit your content needs:

| Layout    | Width            | Best For                                                 |
| --------- | ---------------- | -------------------------------------------------------- |
| **Full**  | 100% of the page | Primary dashboards, detailed views, large visualizations |
| **Half**  | 50% of the page  | Side-by-side comparisons, medium-sized panels            |
| **Third** | 33% of the page  | KPI cards, compact metrics, summary widgets              |

Hover over any widget to reveal layout controls and change its size.

### Reordering Widgets

Drag and drop widgets to reorder them. Grab the drag handle that appears when you hover over a widget and move it to the desired position.

### Editing Widget Content

Click the edit button on any widget to open it in a full-screen editor where you can modify the underlying artifact content.

### Removing Widgets

Click the remove button on a widget to detach it from the app. The underlying artifact is not deleted and can be re-added later.

## Viewing an App

When you open an app from the navigation:

* **Single widget**: The artifact fills the full page height for an immersive experience
* **Multiple widgets**: Widgets are displayed in a responsive grid layout, adapting to the sizes you configured

## Sharing & Permissions

Share apps with team members to provide consistent dashboards across your organization.

| Permission | Capabilities                                       |
| ---------- | -------------------------------------------------- |
| **Owner**  | Full control — edit, share, delete, manage widgets |
| **Editor** | Modify the app and its widgets                     |
| **Viewer** | View the app (read-only)                           |

To share an app, click the **Share** button on any app you own and invite team members with the appropriate permission level.

The share panel also shows which [managed resources](#managed-resources) people you share with can use. Click **Check widgets** to find tools the widgets call that aren't in the bundle yet.

## Managed Resources

Interactive widgets (React artifacts and MCP UI artifacts) call tools and read Lists at runtime. Sharing an app on its own doesn't give viewers access to those tools. Someone who can view the app but has no access to its integration would see the widget fail.

**Managed resources** fix this. They're the owner-approved list of exactly which tools and Lists the app may use, and for whom. When a viewer can't run a tool themselves, the call is checked against this list and, if allowed, runs with the **publisher's** access. The publisher is whoever last published the bundle. Anything not on the list can't be reached through the app.

### Setting up the bundle

{% stepper %}
{% step %}
**Expand the app** In the Apps list, click the app to expand it. Below **Dashboard Widgets** you'll find **Managed Resources**.
{% endstep %}

{% step %}
**Scan widgets** Click **Scan widgets**. DarcyIQ reads every widget and lists the MCP tools and Lists it uses. Click **Add** (or **Add all**) to put them in the bundle. Use **Add** at the top to pick an integration tool or List by hand.
{% endstep %}

{% step %}
**Choose who can use each resource** Each resource has three audience checkboxes:

* **Org**: people in your organization you've shared the app with
* **Portal**: customers viewing the app on a [Project Portal](https://docs.darcyiq.com/organize/projects/portal.md)
* **Public**: anyone with the app's [public link](#public-app-links)

For Lists, the **Writes** switch allows inserting, updating and deleting rows. Lists are read-only by default.
{% endstep %}

{% step %}
**Save and publish** Click **Save**, then **Publish bundle**. Publishing confirms you have access to everything in the bundle; from then on, shared calls run with your access.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Public means public.** There are no per-parameter limits. Any resource enabled for **Public** can be called by anyone with the link, with any parameters, using the publisher's credentials. Only enable Public for tools you'd be comfortable exposing as a public API, and prefer read-only Lists.
{% endhint %}

### Warnings

Each resource shows badges when something needs attention:

| Badge                         | Meaning                                                                                  |
| ----------------------------- | ---------------------------------------------------------------------------------------- |
| **Publisher has no access**   | The publisher can't use this integration or List, so calls will fail                     |
| **Tool disabled by owner**    | The integration owner disabled this tool, so calls will fail                             |
| **Needs approval in chat**    | The tool requires approval in chat; approval doesn't apply to apps, so it runs directly  |
| **Uses personal credentials** | The integration is a personal connection, so it would act as the publisher's own account |
| **Writes need Editor access** | The publisher needs Editor access on the List for row writes                             |

### Rules that keep the bundle safe

* Only **MCP tools** and **Lists** can be bundled. Built-in tools that search across your workspace (web search, account search, and so on) can't be.
* Editors can only add resources they have access to themselves.
* If someone other than the publisher edits the bundle, it's **unpublished** until it's published again, so new resources never start running under someone who didn't approve them.
* The publisher's access is re-checked on every call. If they lose access, calls stop.
* **Unpublish** stops all shared tool calls immediately.
* Every call is logged with who made it, which tool ran, and whether it was allowed.

## Public App Links

Publish an app to a link you can share outside your workspace, for example a free dashboard for prospects or customers.

1. In the Apps list, open the app's **⋯** menu and choose **Public link**.
2. Choose **Anyone with the link** or **Specific people** (signed-in members of your organization).
3. Optionally set a password and an expiry.
4. Leave **Allow live tool calls** on for interactive widgets to load data through the bundle's **Public** resources, or turn it off for a static snapshot.
5. Click **Publish** and copy the link.

The link shows a snapshot of the app's widgets from publish time. Click **Update snapshot** after changing widgets. Live calls are rate-limited per visitor, per app and per organization. Public app links are enabled per organization by the `public_apps` feature flag; turning it off stops live calls on every link immediately.

## Managing Apps

From the Apps list, you can manage all your apps:

| Action                   | Description                                                                    |
| ------------------------ | ------------------------------------------------------------------------------ |
| **Create**               | Build a new app with a name, icon, and initial widget                          |
| **Edit**                 | Update the app name, description, or icon                                      |
| **Enable / Disable**     | Toggle whether the app appears in the sidebar navigation                       |
| **Pin / Unpin**          | Star an app to list it first, with a star, in the Apps menu. Pins are personal |
| **Add / Remove Widgets** | Manage dashboard widgets from the expanded view                                |
| **Share**                | Invite team members and set permission levels                                  |
| **Managed Resources**    | Bundle the tools and Lists widgets may use for viewers                         |
| **Public link**          | Publish the app to a public or restricted link                                 |
| **Open**                 | View the live app page in a new tab                                            |
| **Delete**               | Permanently remove the app (cannot be undone)                                  |

## Integration with Projects

Apps can be linked to projects, allowing you to associate a dashboard directly with a customer engagement or initiative. Select an app when configuring a project to give team members quick access to the relevant dashboard.

Turn on **Share Project App** in the project's portal settings to show the app to portal customers. Interactive widgets appear on the portal only when the app's managed resources are published with **Portal** enabled.

## Building MCP UI Artifacts

Apps are powered by MCP UI artifacts created in **MCP Studio**. To build new artifacts for your dashboards:

1. Navigate to **MCP Studio** from the Apps page or sidebar
2. Build or select an MCP that produces interactive UI artifacts
3. The artifacts become available in the artifact library when creating app widgets

For more on building MCPs, see the [MCP Studio documentation](https://docs.darcyiq.com/build/mcp-studio.md).

## Best Practices

### App Design

1. **Clear Purpose**: Each app should serve a specific function — a sales dashboard, an ops panel, a monitoring view
2. **Widget Balance**: Mix full-width detail views with half and third-width summary cards
3. **Naming Conventions**: Use descriptive names so team members can find apps quickly
4. **Gradual Build-Out**: Start with one or two widgets and expand as you identify what the team needs

### Dashboard Organization

| Practice                   | Implementation                                  | Impact                          |
| -------------------------- | ----------------------------------------------- | ------------------------------- |
| **Group Related Widgets**  | Place related metrics and tools on the same app | Faster decision-making          |
| **Use Layout Wisely**      | Full-width for primary content, thirds for KPIs | Scannable at a glance           |
| **Enable Only When Ready** | Keep apps disabled while configuring            | Clean navigation for the team   |
| **Review Permissions**     | Periodically check who has access               | Maintain security and relevance |

{% hint style="info" %}
**Pro Tip**: Start by creating MCP UI artifacts in MCP Studio, then compose them into an App for a polished dashboard experience your whole team can use.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.darcyiq.com/core-features/apps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
