Skip to main content

Connect a Genie Agent to MCP tools and sources

A Genie Agent can use MCP (Model Context Protocol) tools to pull context from and take actions in external tools and sources. An agent author attaches Databricks-provided connectors or external MCP servers registered in Unity Gateway. Users can then ask the agent to use these tools in Agent mode conversations.

note

Genie Agents were formerly known as Genie Spaces.

How MCP connectors work in a Genie Agent​

MCP connectors let a Genie Agent combine its SQL and file analysis with the external applications your organization already uses. For example, a single conversation can analyze a sales table, pull related context from Google Drive, and draft a summary email. Databricks governs every tool call through Unity Catalog and Unity Gateway. See Govern an MCP.

Genie Agents support two kinds of MCP sources:

  • Databricks-provided connectors: Connectors that Databricks manages for common applications. The following connectors are available:

    • Google Drive: Search and create Google Docs, Sheets, and Slides; edit Docs it created.
    • Gmail: Search, read, and draft email.
    • Google Calendar: Search and create calendar events.
    • Microsoft 365: Search SharePoint, Teams, Outlook, and Calendar; draft Outlook email.
    • Atlassian: Search and update Jira and Confluence.
    • Asana: Search tasks, projects, portfolios, users, and teams, and create or update tasks when write actions are allowed.
    • Glean (Beta): Search across your organization's connected apps using Glean.
    • Slack: Search Slack messages and channels, and send messages.
    • GitHub: Search and update repositories, issues, and pull requests.
  • External MCP servers: Self-hosted or third-party MCP servers that your organization registers in Unity Gateway. See External MCP servers.

Requirements​

The following requirements apply to the agent and its users:

  • Account-only users can't use MCP tools. See Access entitlements.
  • Each user must have an account in each connected MCP tool or source.
  • To attach a connector, the agent author needs EXECUTE on its MCP, plus USE CATALOG and USE SCHEMA on the parent catalog and schema. Connectors the author doesn't have permission to run are unavailable. See Share an MCP.

Add connectors to a Genie Agent​

To attach connectors to a Genie Agent:

  1. Open your Genie Agent.
  2. Open the Sources tab, then click Add.
  3. Select one or more MCP services. You can pick Databricks-provided connectors or external MCP servers registered in Unity Gateway.

How users authenticate to an external MCP server depends on its credentials:

  • Per-user OAuth: Each user must sign in before the agent can use the server's tools.
  • Shared credentials: Users don't sign in. If the shared credential stops working, the agent tells the user that the server's owner must update it.

Configure tools​

After you attach a connector, configure how the agent uses it:

  • Add a clear Description that explains how and when the agent should use the connector's tools. For example, you can instruct the agent on a required ticket-title format or tell it to look up a user's profile at the start of each conversation.
  • Enable or disable individual tools within a connector to scope which actions the agent can take.

Use MCP tools in a conversation​

To use MCP tools in a Genie Agent:

  1. Open a Genie Agent that has MCP connectors attached.

  2. Make sure Agent mode is turned on.

  3. If a connector requires sign-in, authenticate to it from the Sources list or when the agent prompts you.

    If your organization blocks the sign-in, see Additional third-party app configuration.

  4. Send a prompt that uses the connector.

You can also use MCP tools through the Agent mode APIs. If a connector requires sign-in, the API response directs the user to sign in.

Get admin approval for connectors​

Your Slack, Google Workspace, Microsoft 365, or GitHub administrators might need to approve or configure the Databricks app before users can sign in. For the steps for each provider, see Additional third-party app configuration.

Limitations​

The following limitations apply:

  • MCP tools run only in Agent mode. They don't run in Chat mode.
  • A Genie Agent can have up to 10 MCP connections, including both Databricks-provided connectors and external MCP servers.
  • Service principals can't use MCP tools.
  • For compliance guidance for connected applications, see External provider requirements.

The following sections describe limitations for specific connectors.

Google Drive​

  • When authorizing Google Drive, you might see an Unverified app screen. Click Advanced and continue the authorization process.
  • Maximum file size is 25 MB.
  • Only native Google Workspace files (Docs, Sheets, Slides) are supported. PDFs, images, and other binary formats are not supported.
  • The connector can create Google Docs, Sheets, and Slides, and edit Google Docs it created. It can't edit Docs created outside the connector, or edit existing Sheets or Slides.
  • Reading a very large document can be slow.
note

The use and transfer of raw or derived user data received from Google Workspace APIs will adhere to the Google API services User Data Policy, including the Limited Use requirements.

Gmail​

  • The connector can search, read, and draft email, but it can't send email or edit existing messages.
  • The connector can't add Drive files as native Gmail attachments. As a workaround, include links to the files in the email body.

Microsoft 365​

  • Includes SharePoint, OneDrive, Teams, Outlook, Calendar, and online meetings.
  • The connector can draft Outlook email but can't send it.
  • Maximum file size is 25 MB for SharePoint files.
  • Supported SharePoint file types include built-in SharePoint documents, spreadsheets, and presentations, as well as common text-based formats such as .txt, .csv, .json, .md, and others. PDFs, images, and other binary formats are not supported.

Glean (Beta)​

  • Glean is search-only. It can't read a document from a direct link.
  • A metastore admin must first configure the Glean tenant ID before non-admin users can use the connection. The admin can enter the tenant ID when first connecting to Glean.
  • To connect to a specific Glean MCP server, a metastore admin can optionally set the MCP server path (for example, /mcp/eng) when setting up the connection. Leave this field blank to use the default path (/mcp/default). Non-admin users cannot specify or change the Glean MCP server path.

Slack​

  • The connector can't edit or delete a message after sending it.

GitHub​

  • Writes are limited to file contents, issues, and pull requests.
  • By default, the Databricks GitHub MCP connector can access only public repositories. To access private repositories, or to make changes such as committing files or creating issues and pull requests, the repository owner or a GitHub organization administrator must complete additional setup. See Enable GitHub write access and private repository access.
  • GitHub Enterprise Server (the self-hosted version of GitHub) is not supported.

Additional resources​

See the following resources for related information: