Integrations
ZenSearch agents can interact with external platforms through tool integrations. These give agents the ability to read, create, and modify content in third-party services during conversations.
Integrations are distinct from data connectors. Data connectors ingest content into the search index for retrieval. Integrations let agents take real-time actions in external services. Some platforms (like Notion) support both.
Browser Extension
The browser extension is a user-facing delivery surface rather than an agent tool integration, but it is configured from the same Settings > Integrations area in the web app.
- Download the current release build from GitHub Releases
- Install it in Chrome with Load unpacked
- Configure it with a publishable ZenSearch API key
- Optionally enable page-context prompts for the current tab
See Browser Extension for the full installation flow.
Google Workspace
18 agent tools for interacting with Google services. Authenticate via OAuth 2.0 or a Google service account.
Gmail
| Tool | Description |
|---|---|
create_gmail_draft | Create a draft email |
send_gmail_draft | Send a previously created draft |
list_gmail_messages | List and search emails |
get_gmail_message | Read a specific email |
Google Calendar
| Tool | Description |
|---|---|
list_calendar_events | List upcoming events |
get_calendar_event | Get event details |
create_calendar_event | Create a new calendar event |
update_calendar_event | Modify an existing event |
delete_calendar_event | Remove a calendar event |
Google Drive
| Tool | Description |
|---|---|
search_google_drive | Search for files and folders |
get_drive_file | Get file metadata and content |
upload_to_drive | Upload a file |
Google Docs
| Tool | Description |
|---|---|
get_google_doc | Read document content |
create_google_doc | Create a new document |
update_google_doc | Append or modify document content |
Google Sheets
| Tool | Description |
|---|---|
get_google_sheet | Read spreadsheet data |
create_google_sheet | Create a new spreadsheet |
update_google_sheet | Write data to cells |
Setup (Self-Hosted)
Google Workspace integrations support OAuth 2.0 (user authorizes during setup) and Service Account (domain-wide delegation). For OAuth 2.0:
1. Create a Google Cloud Project
- Go to Google Cloud Console
- Create a new project (e.g., "ZenSearch")
2. Enable APIs
In APIs & Services > Library, enable:
- Google Drive API
- Google Sheets API
- Google Docs API
- Gmail API
- Google Calendar API
3. Configure OAuth Consent Screen
- Go to APIs & Services > OAuth consent screen
- Select External user type
- Fill in app name, support email, privacy policy URL
- Add scopes:
drive.readonly,drive.file,spreadsheets,documents,gmail.send,gmail.readonly,gmail.compose,calendar.events,userinfo.email,userinfo.profile,openid - Add test users (required while in Testing mode)
4. Create OAuth Credentials
- Go to APIs & Services > Credentials > Create Credentials > OAuth client ID
- Application type: Web application
- Authorized redirect URI:
https://YOUR_API_DOMAIN/api/v1/integrations/google-workspace/user/auth/callback - Copy the Client ID and Client Secret
5. Set Environment Variables
GWS_OAUTH_CLIENT_ID=your-client-id
GWS_OAUTH_CLIENT_SECRET=your-client-secret
GWS_OAUTH_REDIRECT_URL=https://YOUR_API_DOMAIN/api/v1/integrations/google-workspace/user/auth/callback
Restart the core-api service after setting these values.
Gmail scopes are classified as restricted by Google and require verification (4-6 week review with CASA security assessment). While unverified, users will see a "Google hasn't verified this app" warning they can click through. Non-Gmail scopes (Drive, Sheets, Docs, Calendar) only require a lighter "sensitive" review.
Microsoft 365
33 agent tools for interacting with Microsoft services. Authenticate via OAuth 2.0 through Azure Active Directory.
OneDrive
| Tool | Description |
|---|---|
search_onedrive_files | Search for files in OneDrive |
get_onedrive_file | Get file content and metadata |
upload_onedrive_file | Upload a file to OneDrive |
create_onedrive_folder | Create a folder in OneDrive |
Outlook Email
| Tool | Description |
|---|---|
list_outlook_emails | List recent emails |
get_outlook_email | Get the full content of an email |
create_outlook_draft | Create an email draft |
send_outlook_draft | Send a previously created draft |
reply_to_email | Reply to an email |
forward_email | Forward an email to recipients |
get_email_attachment | Download an email attachment |
Outlook Calendar
| Tool | Description |
|---|---|
list_outlook_events | List calendar events |
get_outlook_event | Get event details |
create_outlook_event | Create a calendar event |
update_outlook_event | Update an existing event |
delete_outlook_event | Delete a calendar event |
Teams Messages
| Tool | Description |
|---|---|
list_teams_messages | List messages from a Teams channel |
send_teams_message | Send a message to a channel |
reply_to_teams_message | Reply to a thread in a channel |
list_teams_chats | List the user's Teams chats |
list_teams_chat_messages | List messages from a chat |
send_teams_chat_message | Send a message in a chat |
Teams Meetings
| Tool | Description |
|---|---|
list_teams_meetings | List Teams online meetings |
get_meeting_transcript | Get a meeting transcript |
get_meeting_attendance | Get meeting attendance report |
list_meeting_chat_messages | List chat messages from a meeting |
To Do
| Tool | Description |
|---|---|
list_todo_tasks | List tasks from Microsoft To Do |
create_todo_task | Create a task |
update_todo_task | Update a task |
People & SharePoint
| Tool | Description |
|---|---|
search_people | Search the organization directory |
list_sharepoint_lists | List SharePoint lists for a site |
get_sharepoint_list_items | Get items from a SharePoint list |
create_sharepoint_list_item | Create a new item in a SharePoint list |
Setup (Self-Hosted)
1. Create Azure App Registration
- Go to Azure Portal > Microsoft Entra ID > App registrations
- Click New registration
- Name:
ZenSearch - Supported account types: Accounts in any organizational directory (Multitenant)
- Redirect URI: Web >
https://YOUR_API_DOMAIN/api/v1/integrations/microsoft365/user/auth/callback - Click Register and copy the Application (client) ID
2. Add API Permissions
Go to API permissions > Add a permission > Microsoft Graph > Delegated permissions and add:
| Feature | Permissions |
|---|---|
| Baseline | openid, profile, email, offline_access, User.Read |
| OneDrive | Files.ReadWrite.All |
| Outlook Mail | Mail.Read, Mail.Send, Mail.ReadWrite |
| Calendar | Calendars.ReadWrite |
| Teams | Chat.ReadWrite, ChannelMessage.Send, Team.ReadBasic.All |
| Meetings | OnlineMeetings.ReadWrite |
| To Do | Tasks.ReadWrite |
| People | People.Read, User.ReadBasic.All |
| SharePoint | Sites.ReadWrite.All |
3. Create Client Secret
- Go to Certificates & secrets > Client secrets > New client secret
- Set expiry (max 24 months) and click Add
- Copy the secret Value immediately (shown only once)
4. Set Environment Variables
M365_OAUTH_CLIENT_ID=your-application-client-id
M365_OAUTH_CLIENT_SECRET=your-secret-value
M365_OAUTH_REDIRECT_URL=https://YOUR_API_DOMAIN/api/v1/integrations/microsoft365/user/auth/callback
M365_OAUTH_TENANT_ID=common
Some permissions (Sites.ReadWrite.All, ChannelMessage.Read.All) require admin consent from the customer's IT admin. Client secrets expire after max 24 months — set a rotation reminder. Consider publisher verification to remove the "unverified app" warning.
Zendesk
14 agent tools for managing support operations. Authenticate via OAuth 2.0.
Tickets
| Tool | Description |
|---|---|
search_zendesk_tickets | Search for support tickets |
get_zendesk_ticket | Get ticket details |
create_zendesk_ticket | Create a new ticket |
update_zendesk_ticket | Update an existing ticket |
list_zendesk_ticket_comments | List comments on a ticket |
add_zendesk_ticket_comment | Add a comment to a ticket |
list_zendesk_ticket_fields | List all ticket field definitions |
get_zendesk_ticket_metrics | Get performance metrics for a ticket |
Help Center
| Tool | Description |
|---|---|
search_help_center_articles | Search help center articles |
get_help_center_article | Read an article |
Users & Organizations
| Tool | Description |
|---|---|
search_zendesk_users | Search for users |
get_zendesk_user | Get user details |
list_zendesk_organizations | List organizations |
get_zendesk_organization | Get organization details |
Setup (Self-Hosted)
1. Create a Zendesk OAuth Client
- Sign in to Zendesk as an admin
- Go to Admin Center > Apps and integrations > APIs > OAuth Clients
- Click Add OAuth client
- Fill in:
- Client name:
ZenSearch - Kind: Confidential
- Redirect URLs:
https://YOUR_API_DOMAIN/api/v1/integrations/zendesk/auth/callback
- Client name:
- Click Save
- Copy the Unique Identifier (Client ID) and Client Secret immediately — the secret is only shown once
2. Set Environment Variables
ZENDESK_OAUTH_CLIENT_ID=your-unique-identifier
ZENDESK_OAUTH_CLIENT_SECRET=your-secret
ZENDESK_OAUTH_REDIRECT_URL=https://YOUR_API_DOMAIN/api/v1/integrations/zendesk/auth/callback
Users will enter their Zendesk subdomain (e.g., your-company) during the connection flow in ZenSearch.
Airtable
8 agent tools for working with Airtable bases and records. Authenticate via API key.
| Tool | Description |
|---|---|
list_airtable_bases | List all accessible bases |
get_airtable_base_schema | Get the schema of a base |
list_airtable_records | List records from a table |
get_airtable_record | Get a single record by ID |
create_airtable_record | Create a new record |
update_airtable_record | Update an existing record |
delete_airtable_record | Delete a record |
add_airtable_comment | Add a comment to a record |
Notion (Agent Tools)
12 agent tools for working with Notion pages and databases. Authenticate via API key (internal integration token).
This is the Notion agent tool integration for creating and editing content. For indexing Notion content into the search index, see the Notion data connector.
| Tool | Description |
|---|---|
search_notion | Search pages and databases |
get_notion_page | Read a page and its content |
create_notion_page | Create a new page |
update_notion_page | Update page properties |
append_notion_blocks | Append content blocks to a page |
get_notion_database | Get database schema |
query_notion_database | Query a database with filters and sorting |
create_notion_database_entry | Add an entry to a database |
update_notion_database_entry | Update a database entry |
add_notion_comment | Add a comment to a page |
list_notion_comments | List comments on a page |
list_notion_users | List workspace users |
Custom Webhook Tools
Organizations can create custom tools by specifying a webhook endpoint that the agent calls during execution. This lets you extend agent capabilities with your own APIs and internal services.
Creating a Custom Tool
- Navigate to Settings > Integrations > Custom Tools
- Click Create Tool
- Configure the tool:
| Field | Description | Required |
|---|---|---|
| Name | Tool name (used by the agent) | Yes |
| Description | What the tool does (helps the agent decide when to use it) | Yes |
| URL | Webhook endpoint to call | Yes |
| Method | HTTP method (GET, POST, PUT, DELETE) | Yes |
| Parameters | JSON schema defining tool inputs | No |
| Auth Method | How to authenticate requests | No |
Authentication Options
| Method | Description |
|---|---|
| None | No authentication |
| API Key | Send an API key in a header |
| Basic Auth | Username and password |
| Custom Headers | Arbitrary headers (e.g., Bearer tokens) |
How It Works
When an agent invokes a custom tool:
- The agent provides parameter values based on the JSON schema
- ZenSearch sends an HTTP request to the configured endpoint
- The response body is returned to the agent as the tool result
- The agent incorporates the result into its reasoning
Example: Internal Ticketing System
Name: create_internal_ticket
Description: Create a ticket in our internal issue tracker
URL: https://internal-api.example.com/tickets
Method: POST
Auth: API Key (X-API-Key header)
Parameters:
- title (string, required): Ticket title
- description (string, required): Ticket description
- priority (string, optional): low, medium, high
MCP Server Support
ZenSearch integrates with external tool servers following the Model Context Protocol (MCP) standard. MCP servers expose tools, resources, and prompts through a standardized interface, allowing you to connect any MCP-compatible tool provider to your agents.
What Is MCP?
The Model Context Protocol is an open standard for connecting AI models to external tools and data sources. MCP servers expose capabilities that ZenSearch agents can discover and use automatically.
Connecting an MCP Server
- Navigate to Settings > Integrations > MCP Servers
- Click Add Server
- Provide the server URL and authentication details
- ZenSearch discovers available tools automatically
- Enable the tools you want agents to use
Supported Transports
- HTTP + SSE: Server-sent events over HTTP
- Stdio: Local process communication
Tool Discovery
Once connected, ZenSearch automatically discovers tools exposed by the MCP server. Each tool appears in the agent tool selection with:
- Name and description (from the MCP server)
- Input schema (parameters the tool accepts)
- Server origin (which MCP server provides it)
Managing Integrations
Enabling Tools per Agent
Each agent can be configured with a specific set of integration tools:
- Edit the agent configuration
- In the Tools section, browse available integration tools
- Enable or disable individual tools
- Save the agent
Credential Management
Integration credentials are stored securely and encrypted at rest. Credentials are managed at the team level:
- OAuth tokens are refreshed automatically
- API keys can be rotated without reconfiguring agents
- Credentials are never exposed in agent responses or logs
Rate Limiting
External API calls made by agents respect the rate limits of the target platform. ZenSearch tracks usage and throttles requests to avoid exceeding provider limits.
Next Steps
- Agents - Configure agents with integration tools
- Canvas & Artifacts - Persistent content objects
- Connectors Overview - Data source connectors