Skip to main content
Last updated on

Connect agents to external services

Preview

This feature is in Public Preview.

Connect your AI agents to external applications like Slack, Google Calendar, or any service with an API. Databricks provides several approaches depending on whether the external service has an MCP server, whether you need per-user authentication, or whether you prefer to call APIs directly from agent code. All approaches rely on a Unity Catalog HTTP connection to securely manage credentials and govern access to external services.

Approach

Recommended use case

External MCP servers

Use this approach for services that publish an MCP server. It provides automatic tool discovery and works with standard SDKs.

Managed OAuth

Use this approach for Google Drive or SharePoint integrations. Databricks manages the OAuth credentials, so no app registration is required.

UC connections proxy

Use this approach to make direct REST API calls from agent code using the external service's own client SDK.

UC function tools

Use this approach for SQL-based tool definitions that wrap the http_request() function.

Requirements​

  • A Unity Catalog HTTP connection for your external application. Unity Catalog connections provide secure, governed credential management and enable multiple authentication methods, including OAuth 2.0 user-to-machine and machine-to-machine authentication.

External MCP servers​

If the external service has an MCP server available, Databricks recommends connecting through external MCP servers. MCP servers provide automatic tool discovery, simplified integration, and per-user authentication. See Use external MCP servers for installation methods, programmatic usage, and authentication details.

Add an external MCP server to your agent​

After you register the external MCP server as a Unity Catalog connection, connect your agent to it using the managed MCP URL: https://<workspace-hostname>/api/2.0/mcp/external/{connection_name}. Replace <connection-name> with the name of your Unity Catalog connection.

Python
from agents import Agent, Runner
from databricks.sdk import WorkspaceClient
from databricks_openai.agents import McpServer

workspace_client = WorkspaceClient()
host = workspace_client.config.host

async with McpServer(
    url=f"{host}/api/2.0/mcp/external/<connection-name>",
    name="external-service",
    workspace_client=workspace_client,
) as external_server:
    agent = Agent(
        name="Connected agent",
        instructions="You are a helpful assistant with access to external services.",
        model="databricks-claude-sonnet-4-5",
        mcp_servers=[external_server],
    )
    result = await Runner.run(agent, "Send a Slack message to the team about the deployment")
    print(result.final_output)

Grant the app access to the Unity Catalog connection in databricks.yml:

YAML
resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_connection'
          uc_securable:
            securable_full_name: '<connection-name>'
            securable_type: 'CONNECTION'
            permission: 'USE_CONNECTION'

Managed OAuth​

Databricks offers managed OAuth flows for select API tool providers. You don't need to register your own OAuth app or manage credentials. Databricks recommends Managed OAuth for development and testing. If production use cases require generating custom OAuth credentials, see the providers' documentation for more information.

The following integrations use Databricks-managed OAuth credentials stored securely in the backend.

Provider

Configuration notes

Supported scopes

Description

Google Drive API

None

https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/documents.readonly https://www.googleapis.com/auth/spreadsheets.readonly offline_access

Read-only access to Google Drive files.

SharePoint API

None

https://graph.microsoft.com/Sites.Read.All offline_access openid profile

Read-only access to SharePoint sites.

To set up managed OAuth, create an HTTP connection with the OAuth User to Machine Per User auth type and select your provider from the OAuth Provider drop-down menu. For detailed steps, see Install an external MCP server.

Each user is prompted to authorize with the provider on first use.

If needed, allowlist the following redirect URIs used by managed OAuth:

Cloud

Redirect URI

AWS

https://oregon.cloud.databricks.com/api/2.0/http/oauth/redirect

Azure

https://westus.azuredatabricks.net/api/2.0/http/oauth/redirect

GCP

https://us-central1.gcp.databricks.com/api/2.0/http/oauth/redirect

UC connections proxy endpoint​

Use the Unity Catalog connections proxy endpoint with the external service's own client SDK to call REST APIs directly from agent code. Point the SDK's base URL to the proxy endpoint and use your Databricks token as the API key. Databricks authenticates the request and automatically injects the external service's credentials from the Unity Catalog connection. Your code never handles the external service's tokens directly.

Permissions required: USE CONNECTION on the connection object.

Use DatabricksOpenAI to route calls to external OpenAI through the Unity Catalog connections proxy. First, create a Unity Catalog HTTP connection using your OpenAI API key stored as a Databricks secret:

SQL
CREATE CONNECTION openai_connection TYPE HTTP
OPTIONS (
  host 'https://api.openai.com',
  base_path '/v1',
  bearer_token secret ('<secret-scope>', '<secret-key>')
);

Then install the databricks-openai package and use the proxy URL and workspace client in your agent code:

Bash
pip install databricks-openai
Python
from databricks_openai import DatabricksOpenAI
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

client = DatabricksOpenAI(
    workspace_client=w,
    base_url=f"{w.config.host}/api/2.0/unity-catalog/connections/openai_connection/proxy/",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

UC function tools with HTTP connections​

note

Databricks recommends using MCP servers or the UC connections proxy for new integrations. UC function tools with http_request remain supported but are no longer the recommended approach.

You can create a Unity Catalog function that wraps http_request() to call external services. This approach is useful for SQL-based tool definitions. See Create AI agent tools using Unity Catalog functions for details on creating UC function tools.

The following example creates a Unity Catalog function tool that posts a message to Slack:

SQL
CREATE OR REPLACE FUNCTION main.default.slack_post_message(
  text STRING COMMENT 'message content'
)
RETURNS STRING
COMMENT 'Sends a Slack message by passing in the message and returns the response received from the external service.'
RETURN (http_request(
  conn => 'test_sql_slack',
  method => 'POST',
  path => '/api/chat.postMessage',
  json => to_json(named_struct(
    'channel', "C032G2DAH3",
    'text', text
  ))
)).text

See CREATE FUNCTION (SQL and Python).

note

SQL access with http_request is blocked for the User-to-Machine Per User connection type. Use the Python Databricks SDK instead.

Example notebooks​

Connect an agent to Slack​

See Connect an AI agent to Slack.

External connection tools​

The following notebooks demonstrate creating AI agent tools that connect to Slack, OpenAI, and Azure AI search.

Slack messaging agent tool

Open notebook in new tab

Microsoft Graph API agent tool

Open notebook in new tab

Azure AI Search agent tool

Open notebook in new tab

Limitations​

  • External MCP connections don't support private connectivity to resources in your VPC using Private Service Connect. If your AI agents need to connect to resources in your VPC, reach out to your support team.