> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runorion.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Orion is a collaborative analytics platform built by Gravity (bygravity.com). It connects to data warehouses, to Looker and dbt for existing business logic, and to a small set of external-context sources, and it lets teams ask questions in natural language to get shared analyses, dashboards, reports, and slide decks. The Connecting Data Sources page is the authoritative list of supported sources. When referencing Orion features, always link to the relevant documentation page. Orion is not open-source; it is a commercial SaaS product accessed at runorion.com.

# MCP Connectors

> Let Orion call tools on outside MCP servers

MCP Connectors lets a Tenant Admin register an outside MCP server, such as Stripe or Notion, so Orion can call its tools in chat. Orion's own [MCP Server](https://docs.runorion.com/mcp/overview.md) is the opposite direction: it exposes Orion to outside clients like Claude. **Settings → Connectors** is a third thing, where you link your own accounts, such as [Slack](https://docs.runorion.com/profile-settings/integrations.md).

> [!NOTE]
>
> MCP Connectors are not available on Orion trial workspaces.

Tenant Admins see every server. [Group Admins](https://docs.runorion.com/configuration/groups.md#roles-at-a-glance) can open the page. A Group Admin with the Analyst workspace role sees only servers that are on and open to the workspace or one of their groups. One whose workspace role is Viewer sees none. Only Tenant Admins can add, change, or delete a server.

## Open MCP Connectors

1. Click **Admin Settings** in the left-hand navigation menu
2. Select **Integrations**
3. Open the **MCP servers** card

The page is titled **MCP Connectors**. It has two tabs, **Connected** and **Browse Apps**. **Connected** lists the registered servers you can see, each with an on and off switch. The tab opens on **Browse Apps** until you register the first server.

## Add an app from Browse Apps

**Browse Apps** is a fixed catalog of vendor-hosted servers. Filter it with the category chips or **Search apps**. A card says **One-click sign-in** when Orion registers itself with the vendor. It says **Needs a Xero app**, with the vendor's name, when an admin must first create an app in the vendor's own settings.

1. Click an app's card
2. Read the dialog. **Requires** names the vendor plan or role you need, where one applies
3. Pick a **Region** if the dialog offers one
4. Click the add button, such as **Add Stripe**

Orion opens the new server's page. An app that is already registered shows an **Added** badge, and its dialog offers a manage button, such as **Manage Stripe**, instead. For an app that needs its own vendor app, the server's **Settings** tab shows a redirect URI to paste into that app. Save the client ID and secret there.

Every catalog app signs in with OAuth, so each person connects their own account, per project.

## Add a custom server

Click **Add Custom MCP** in the upper-right corner of the page.

1. Enter the **MCP server URL**. It must be a public address. Orion suggests a **Name** and **Display name** from the domain and shows a favicon **Preview**
2. Edit the **Name** if you like. It starts with a letter, uses only lowercase letters, numbers, and hyphens, and is at most 32 characters
3. Describe the server under **What it does**. Orion reads this to decide when to use the server, and the field is required
4. Choose **Authentication** and fill in what it asks for
5. Click **Connect**, or **Register server** for OAuth

Orion contacts the server, discovers its tools, and opens the server's page so you can review them.

Authentication cannot change after registration. Choose carefully between the two types.

| Type | What you enter | Who signs in |
| - | - | - |
| **Shared headers** | One or more header name and value pairs, such as `Authorization` | Everyone uses the same credential |
| **OAuth · each user's account** | Optional **Client ID**, **Client secret**, and **Allowed permissions** | Each person connects their own account |

Header values are stored encrypted and sent on every request. You cannot view a value after saving it. Click  to remove a header row. For OAuth, leave **Client ID** blank to register automatically when the server supports it.

If the URL is not accepted, the form says "Enter the full URL of the MCP endpoint, starting with https\://." If Orion cannot reach the server, it says "Orion could not connect to this MCP server. Check the URL and headers, then try again." An address Orion refuses, such as a private one, shows only the generic "Failed to add the MCP server".

## Review the tools

A new server is stored with every tool turned off. Open it from **Connected** and use the **Tools** tab. Nothing runs in chat until you review the tools and save.

1. Search the list, or use the filter to find the tools marked **Needs review**
2. Set each tool's access to **Read only** or **Writes data**
3. Turn off the tools you do not want. On the first review the form selects every tool, so the header reads "N of N selected". To start from none, choose **Disable all** in **Bulk actions**
4. Click **Confirm tools**. Once nothing needs review, the button reads **Save changes**
5. In the review dialog, check every tool. Each reads "Will be enabled" or "Will stay disabled". Then click **Confirm tools and save**

**Bulk actions** apply to every tool, including those the filter hides.

The classification is yours to set. The dialog says: "These classifications come from the server until you confirm them." Classify any tool that changes data as **Writes data**, because write tools ask for approval in chat.

For an OAuth server, connect a **Catalog review account** at the top of **Tools** first. Orion uses it only to discover and review tools. Until the OAuth registration is finished, the tab says "Finish OAuth registration in Settings before connecting your review account."

### Refresh and changed tools

Click **Refresh tools** to check the server again. Save pending edits first, or the button is disabled. Orion then lists what is **New**, **Changed**, or **Removed**, or says "No changes. The tools match what you approved." New and changed tools stay off until you review and confirm them.

A server that changed a tool after you approved it shows a **Tools changed** badge. Its page says "This server changed its tools since you approved them. Orion will not call it until you refresh and review the tools." On a shared-header server, an **Unreachable** badge means the last refresh got no answer, and Orion does not use it until you refresh.

## Choose who can use a server

Open the **Access** tab. Under **Who can use this connector**, choose **Entire workspace** or **Selected groups**. With **Selected groups**, pick at least one group. An empty selection does not grant workspace access.

Access is only the first gate. Users also need an eligible role, access to their project, and their own OAuth connection when the server requires one. Viewers cannot use connectors. Tenant Admins can also assign servers from a group's **Integrations** tab.

The switch on each row of **Connected** turns a server on or off for everyone. A Tenant Admin can still try a turned-off server to test it.

## Turn a connector on in a project

Registering a server does not give any chat its tools. Each project opts in.

1. Open the project's **Settings** and select the **Connectors** tab
2. Turn on the server's switch, such as **Use Stripe in this project**

Only a project admin with the Analyst or Admin role can change this. Other Analysts and Admins see only the servers the project already uses, and Viewers see no connectors section. A server a Tenant Admin has turned off cannot be switched on, and its row says "Disabled by a workspace administrator". Turning a server off asks you to confirm and warns that every personal connection in the project is disconnected and workflows using it stop.

For an OAuth server, each member then clicks **Connect account**. The tab shows "Your account is connected", "Your account is not connected", or "Your account needs reconnecting". A shared-header server shows "Uses workspace credentials". If no tool is enabled and reviewed, the tab says "An administrator must review and enable tools before Orion can call them."

## Use a connector in chat

Once a server is enabled, reviewed, and opted in for the project, Orion can offer its tools in a chat in that project. To point Orion at one server, type `@` in the chat input and choose it under **MCP Connectors**. The menu lists only servers you can use in this project, with no **Unreachable** or **Tools changed** badge and at least one enabled, reviewed tool. A **Writes data** tool stops until you approve it. On the web app, an approval card shows **Approve** and **Deny**. On the CLI and `ask_orion`, the reply carries an approval code instead, and the calling agent asks its user to confirm it. The tool runs only after approval.

> [!WARNING]
>
> Every call sends its arguments to the outside server. **Read only** is the label an admin chose, not a guarantee about what the server does with the data.

Connector tools run in chat on the web app, the CLI, and `ask_orion`. They do not run in Slack or Gemini Enterprise, where one identity may serve several people. A Workflow step can also call a connector. See [Calling a Connector](https://docs.runorion.com/workflows/advanced.md#calling-a-connector).

## Change or delete a server

Open the **Settings** tab to change the **Display name**, **URL**, **What it does**, headers, or OAuth fields. Click **Save changes**. Use **Replace headers** to enter new values, because stored values are never shown.

Changing the URL has consequences. It clears the reviewed tools and turns every tool off until you review them again. On an OAuth server it also disconnects every account. On a shared-header server, enter the headers again, because Orion will not send the old ones to a new address.

To remove a server, click **Delete** at the bottom left of its page and confirm. The dialog says: "Chats lose its tools right away, and workflow steps that call it will fail until they are changed. Stored credentials and account connections are deleted."

## Who can do what

| Role | What they can do |
| - | - |
| Tenant Admin | Add, change, refresh, and delete servers. Use every server, including turned-off ones |
| Group Admin | Open the page. With the Analyst workspace role, see the servers open to them; with Viewer, see none. Cannot add, change, or delete a server |
| Analyst | Use an enabled server that is open to the workspace or to one of their groups |
| Viewer | Cannot use connectors |

A project admin decides which servers a project uses. See [Projects](https://docs.runorion.com/core-concepts/projects.md) for the project roles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.