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.

info

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.

At a glance

Integration	Tools	Auth	Reads	Writes
Google Workspace	18	OAuth 2.0 / Service Account	Gmail, Calendar, Drive, Docs, Sheets	Drafts, events, files, docs, sheets
Microsoft 365	33	OAuth 2.0 (Azure AD)	OneDrive, Outlook, Calendar, Teams, To Do, People, SharePoint	Files, emails, events, Teams messages, tasks, SharePoint items
Zendesk	14	OAuth 2.0	Tickets, comments, help center, users, orgs	Tickets, ticket comments
Airtable	8	API key	Bases, schemas, records	Records, comments
Notion (tools)	12	API key (internal integration token)	Pages, databases, comments, users	Pages, database entries, comments
GitHub	19	Per-user OAuth 2.0	Code, PRs, issues, labels, milestones, repos, workflow runs	Issues, comments, PR reviews, branches, reviewers, files, pull requests, merges
Slack	10	Per-user OAuth 2.0	Message search, channels, channel history	Messages, edits, reactions, ephemeral messages, DMs, pins
Salesforce	10	Per-user OAuth 2.0	Objects, records, SOQL, aggregates, picklists, record types	Records (create / update)
SAP S/4HANA	5	Team connector credential	OData entity sets, records	Records (create / update)
Jira	10	Per-user OAuth 2.0	Issues, statuses, workflow statuses	Issues, comments, transitions, worklogs, assignments
ServiceNow	16	Team connector credential	Incidents, KB, changes, problems, CMDB, tables	Incidents, changes, comments
HubSpot	11	Per-user OAuth 2.0	Records, object types, pipelines, properties, notes	Records, associations, notes
Confluence	5	Per-user OAuth 2.0	Pages	Pages, comments
Miro	5	Per-user OAuth 2.0	Boards, items (sticky notes, shapes, cards, frames, text, images, embeds), teams	n/a (Phase 1, read-only)
Datadog	5	API key + Application key	Logs (v2), events (v1), metrics (v1), monitors — site-region aware	n/a (read-only)
Sentry	4	Internal Integration auth token	Issues, sample events, projects, per-event Discover search — region-aware (US / EU SaaS)	n/a (read-only)
PagerDuty	1	OAuth 2.0 (shared with on-call sync)	n/a	Incidents
Google Analytics	4	OAuth 2.0 (per-user, analytics.readonly)	GA4 properties, metric/dimension catalogue, reports, realtime	n/a (read-only)
Mixpanel	4	Service Account credentials (per-user, project-scoped)	Event names, segmentation, funnels, retention — region-aware (US / EU)	n/a (read-only)
PostHog	6	Per-user OAuth (PKCE) or Personal API Key	Dashboards, events, property definitions, HogQL / insight / funnel queries — US / EU Cloud + self-hosted	n/a (read-only)
Web Search	1	None / per-backend	The public web	n/a
Custom Webhook Tools	unbounded	configurable	Anything you wire up	Anything you wire up
MCP Servers	dynamic	per-server	Per server's catalog	Per server's catalog

The pages below cover each integration's tool list and setup.

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

1. Go to Google Cloud Console
2. 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

1. Go to APIs & Services > OAuth consent screen
2. Select External user type
3. Fill in app name, support email, privacy policy URL
4. Add scopes: drive.readonly, drive.file, spreadsheets, documents, gmail.send, gmail.readonly, gmail.compose, calendar.events, userinfo.email, userinfo.profile, openid
5. Add test users (required while in Testing mode)

4. Create OAuth Credentials

1. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID
2. Application type: Web application
3. Authorized redirect URI: https://YOUR_API_DOMAIN/api/v1/integrations/google-workspace/user/auth/callback
4. 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.

note

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

1. Go to Azure Portal > Microsoft Entra ID > App registrations
2. Click New registration
3. Name: ZenSearch
4. Supported account types: Accounts in any organizational directory (Multitenant)
5. Redirect URI: Web > https://YOUR_API_DOMAIN/api/v1/integrations/microsoft365/user/auth/callback
6. 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

1. Go to Certificates & secrets > Client secrets > New client secret
2. Set expiry (max 24 months) and click Add
3. 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

note

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

1. Sign in to Zendesk as an admin
2. Go to Admin Center > Apps and integrations > APIs > OAuth Clients
3. Click Add OAuth client
4. Fill in:
   • Client name: ZenSearch
   • Kind: Confidential
   • Redirect URLs: https://YOUR_API_DOMAIN/api/v1/integrations/zendesk/auth/callback
5. Click Save
6. 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).

info

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

Connector agent tools (writes)

These integrations layer agent write tools on top of the data connectors of the same name. The connector ingests content for search; these tools let an agent take live actions in the same system during a conversation or automation.

All writes are approval-gated: the first time an agent calls one, the run pauses on an approval card (Human Approval) — reads never pause. On automation runs, prose writes (issue bodies, comments, messages, pages) also get a transparency footnote appended so readers know the content is agent-authored; structured-record writes (Salesforce / SAP / HubSpot records) and no-prose actions (reactions, pins, assignments) are not footnoted.

GitHub

19 tools — per-user OAuth.

• Reads (T2): search_github_code, search_github_prs, get_github_pr, search_github_issues, get_github_issue, list_github_labels, list_github_milestones, list_github_repositories, list_github_workflow_runs
• Writes (T3): create_github_issue, update_github_issue, add_github_comment, create_github_pr_review, create_github_branch, request_github_reviewers
• Writes (T4 — harder to undo): create_github_file, update_github_file, create_github_pull_request, merge_github_pull_request

create_github_file / update_github_file alter repo history, opening a pull request can trip CI/CD, and merging is history-irreversible — so these gate at T4. merge_github_pull_request also requires the reviewed head commit SHA (expected_head_sha) as a merge precondition, so the merge is rejected if new commits landed after the approval.

Slack

10 tools — per-user OAuth (per-user xoxp- token; no team-bot fallback).

• Reads (T2): search_slack_messages, list_slack_channels, list_slack_channel_messages
• Writes (T3): send_slack_message, update_slack_message, add_slack_reaction, remove_slack_reaction, send_slack_ephemeral_message, send_slack_dm, pin_slack_message

Salesforce

10 tools — per-user OAuth. Writes run as the connected user and are gated by that user's Salesforce field-level security.

• Reads (T2): describe_salesforce_object, search_salesforce_records, get_salesforce_record, query_salesforce_soql, aggregate_salesforce_records, list_salesforce_sobjects, list_salesforce_record_types, list_salesforce_picklist_values
• Writes (T3): create_salesforce_record, update_salesforce_record

SAP S/4HANA

5 tools — team connector credential (not per-user OAuth). Writes run as the connector's SAP user; SAP's own write authorizations gate what may be created, and SAP Gateway CSRF protection is handled automatically.

• Reads (T0): list_sap_entity_sets, search_sap_records, get_sap_record
• Writes (T3): create_sap_record, update_sap_record

Jira

10 tools — per-user OAuth (Atlassian).

• Reads (T2): search_jira_issues, get_jira_issue, get_jira_status_categories, list_jira_workflow_statuses
• Writes (T3): create_jira_issue, update_jira_issue, add_jira_comment, transition_jira_issue, add_jira_worklog, assign_jira_issue

ServiceNow

16 tools — team connector credential (OAuth 2.0 or Basic-auth service account on the connector).

• Reads (T2): search_servicenow_incidents, get_servicenow_incident, search_servicenow_kb, get_servicenow_kb_article, search_servicenow_changes, get_servicenow_change, search_servicenow_problems, query_servicenow_cmdb, list_servicenow_tables, describe_servicenow_table, list_servicenow_choice_values
• Writes (T3): create_servicenow_incident, update_servicenow_incident, add_servicenow_comment, create_servicenow_change, update_servicenow_change

HubSpot

11 tools — per-user OAuth.

• Reads (T2): search_hubspot_records, get_hubspot_record, list_hubspot_object_types, list_hubspot_pipelines, list_hubspot_properties, get_hubspot_note, list_hubspot_notes
• Writes (T3): create_hubspot_record, update_hubspot_record, create_hubspot_association, add_hubspot_note

Confluence

5 tools — per-user OAuth (Atlassian).

• Reads (T2): search_confluence_pages, get_confluence_page
• Writes (T3): create_confluence_page, update_confluence_page, add_confluence_comment

Miro

5 read-only agent tools for navigating Miro boards and their content. Miro is agent-tool-only (no data ingestion / collector): every query hits the Miro API in real time using the connected user's OAuth grant.

Tool	Description
list_miro_boards	List the user's accessible boards. Miro has no full-text content search across boards — this matches board NAMES only. Filter by Miro team, owner, or project; sort by last modified / created / opened / alphabetically. Cursor-paginated.
get_miro_board	Fetch full metadata for a single board: name, description, view link, owner, team, project, created/modified timestamps.
list_miro_board_items	Read board content — sticky notes, text, shapes, cards, frames, images, embeds, documents. Each item's human-readable surface is normalized into a plain_text field so the agent reasons over boards uniformly. Filterable by item type.
get_miro_item	Fetch a single item by board+item ID for the full type-specific data (sticky-note style, card assignee / due date, embed URL, etc.).
list_miro_teams	List Miro teams under the connected user's organization. Use this discovery call before list_miro_boards when scoping to a specific team — the miro_team_id filter needs Miro's internal ID, not the team name.

Auth model (per-user OAuth)

Miro uses per-user OAuth, not a team-shared API key. Each team member connects their own Miro account through the standard inline auth flow (ADR-023) — the first chat invocation surfaces a "Connect Miro" card; subsequent calls use the saved grant. There is no team-shared Miro credential surface today, and collector ingestion of Miro boards is out of scope for Phase 1, so the agent tool path is the only credentialed Miro surface.

This differs from Datadog (shared team API keys) and matches the HubSpot / Salesforce / Atlassian pattern.

Plain-text extraction

Miro items have type-specific shapes — a sticky note carries data.content, a card has data.title + data.description, a frame has data.title, an embed has data.url, and so on. The adapter normalizes each item's human-readable surface into a single plain_text field so an agent can answer "what action items did we capture on this board?" without branching on item type. The raw data map is also returned for full type-aware fidelity (future write tools or type-specific filters can use it without a second round-trip).

Setup

1. In Miro: visit Profile settings → Your apps → Create new app. Add a redirect URI matching <server>/api/v1/integrations/miro/user/auth/callback.
2. Grant the app scopes: boards:read, team:read, identity:read.
3. In ZenSearch: set MIRO_OAUTH_CLIENT_ID, MIRO_OAUTH_CLIENT_SECRET, and MIRO_OAUTH_REDIRECT_URL env vars (or configure via the platform admin OAuth Clients page).
4. Restart core-api. The Connect-Miro flow lights up automatically once the env resolves — no team-admin connector form to fill out.
5. Each team member completes a one-time OAuth popup the first time they invoke a Miro tool from chat.

Per-user credentials are stored encrypted at rest (AES-GCM via CREDENTIAL_ENCRYPTION_KEY) in user_connector_credentials(provider=miro). Miro stamps the user's team_id / user_id / org_id directly on the OAuth token response, so the callback handler captures them without a separate identity round-trip.

Phase 1 scope

The Phase 1 surface is intentionally read-only. Write tools (create sticky note, update item, add comment) and collector ingestion of board content are deferred until usage signals which paths teams actually need.

Datadog

5 agent tools for live observability — typically used for incident triage. Datadog is agent-tool-only (no data ingestion / collector): every query hits the Datadog API in real time. Configure under Integrations → Datadog.

Tool	Description
search_datadog_logs	Search Datadog logs (Logs Search v2) with optional service, env, host, status, query, and time-window filters. Returns parsed log entries with timestamp, service, host, status, message, tags, and attributes.
search_datadog_events	List Datadog events (Events List v1) over a time window with optional priority, source, tag, and aggregation filters. Useful for correlating deploys / alerts / incidents alongside logs.
query_datadog_metrics	Query Datadog metrics (v1 /api/v1/query). Accepts Datadog's metric query language (e.g. avg:trace.http.request.duration{service:checkout}.rollup(60)). Returns one or more timeseries per the query's grouping — answers the numeric / aggregate questions logs and events can't.
list_datadog_monitors	List Datadog monitors with optional filters (group_states, name, tags, monitor_tags). Use for "what's currently alerting?" by passing group_states=[Alert]. Pairs with get_datadog_monitor for drill-in.
get_datadog_monitor	Fetch a single Datadog monitor's full detail by numeric ID — alert query, message body, options (notify_no_data, thresholds, evaluation delay), and per-group state breakdown when the monitor groups by tag. Surfaces last-triggered / last-resolved timestamps per group.

Triage workflow

The 5 tools were designed to compose for "Sarah's Monday morning" incident triage:

1. "What's currently alerting?" → list_datadog_monitors(group_states=["Alert"])
2. "Why is monitor 12345 alerting?" → get_datadog_monitor(monitor_id=12345) for the alert condition + per-group state
3. "What's the error rate this week?" → query_datadog_metrics(query="avg:error_rate{service:X}") for the numeric trend
4. "What changed?" → search_datadog_events(from="now-2h", sources=["github"]) for deploy markers
5. "Show me the actual errors" → search_datadog_logs(query="status:error service:X", from="now-30m") for stack traces

Region selector

Datadog runs in six regions; the connector form requires you to pick yours so the adapter talks to the correct API host:

Site	API host
US1 (default)	api.datadoghq.com
US3	api.us3.datadoghq.com
US5	api.us5.datadoghq.com
EU	api.datadoghq.eu
AP1	api.ap1.datadoghq.com
US1-FED	api.ddog-gov.com

The backend gates the configured site against a closed Datadog-domain allowlist (IsAllowedDatadogSite) as a credential-exfiltration guard — DD-API-KEY + DD-APPLICATION-KEY headers will never be sent to an off-domain host even if a stale connector row predates the check.

Setup

1. In Datadog: Organization Settings → API Keys → create an API key.
2. In Datadog: Organization Settings → Application Keys → create an Application key. Application keys are bound to a Datadog user — prefer a service-account user, and scope the key to logs_read_data + events_read (the minimum the two tools need).
3. In ZenSearch: Integrations → Datadog → Add source.
4. Pick your region, paste the API key and Application key.
5. Test connection — issues a real SearchLogs(now-1m → now, limit:1) against the configured site. Green = the dual-key auth works.

Credentials are stored encrypted at rest (AES-GCM via CREDENTIAL_ENCRYPTION_KEY).

Auth model (no inline chat auth)

Datadog uses shared team credentials, not per-user OAuth. A single API + Application key pair is configured by a team admin and every team member's chats use it transparently — there's no "Connect Datadog" button in chat. This differs from HubSpot / Salesforce / Atlassian (which surface inline auth via ADR-023's per-user OAuth flow) because Datadog's auth model has no per-user identity to grant.

Sentry

4 agent tools for live error triage. Sentry is agent-tool-only (no data ingestion / collector): every query hits the Sentry API in real time. Pairs naturally with Datadog — Datadog gives logs and events, Sentry gives grouped error issues with sample stack traces. Configure under Integrations → Sentry.

Tool	Description
search_sentry_issues	Search Sentry issues with optional project, environment, query, and stats-period filters. Returns grouped issues with counts, first/last-seen, and project context. Sentry's native query syntax (e.g. is:unresolved level:error environment:prod) flows through unchanged.
get_sentry_issue	Fetch a Sentry issue by numeric ID plus a summary of its most recent event (sample stack trace, tags, platform). Pairs with search_sentry_issues to drill into a specific error.
list_sentry_projects	List the Sentry projects the connected account has access to. Use as the first call when the user mentions Sentry but the project slug is unknown — the "describe before query" introspection helper.
search_sentry_events	Per-event Discover search — the finer-grained view alongside search_sentry_issues. Use when the LLM needs event-level detail rather than the issue-grouped view: per-browser breakdown of an issue, per-release timeline, custom Discover aggregations (count(), count_unique(user.email)). Sentry's Discover query syntax (event.type:error browser.name:Chrome, release:v1.2.3) is richer than the issues syntax, and fields lets you control the projection (custom columns appear in each event's fields map).

Region selector

Sentry SaaS runs in two regions; the connector form requires you to pick yours so the adapter talks to the correct API host:

Host	Region
sentry.io (default)	US
de.sentry.io	EU

The backend gates the configured host against a closed Sentry-domain allowlist (IsAllowedSentryHost) as a credential-exfiltration guard — the Authorization: Bearer header will never be sent to an off-domain host even if a stale connector row predates the check. Self-hosted Sentry (customer-defined hostname) is intentionally not supported in this phase — it requires a different validator shape and is tracked as a Phase 2 follow-up.

Setup

1. In Sentry: Organization Settings → Custom Integrations → Create New Integration → Internal Integration.
2. Name the integration (e.g. "ZenSearch agents") and grant these scopes:
   • org:read — required for the projects-list endpoint
   • project:read — required to read project metadata embedded on issues
   • event:read — required for search_sentry_issues (issues are events), get_sentry_issue's sample-event fetch, and search_sentry_events (Discover events endpoint)
3. Save → copy the generated token (it's only shown once).
4. In ZenSearch: Integrations → Sentry → Add source.
5. Pick your region, paste your organization slug (the URL fragment in https://sentry.io/organizations/<slug>/), and the auth token.
6. Test connection — issues a real ListProjects call against the configured host. Green = the token + org slug + host all work.

Credentials are stored encrypted at rest (AES-GCM via CREDENTIAL_ENCRYPTION_KEY).

Auth model (no inline chat auth)

Sentry uses shared team credentials, not per-user OAuth. A single Internal Integration token is configured by a team admin and every team member's chats use it transparently — there's no "Connect Sentry" button in chat. Pattern identical to Datadog. Personal Auth Tokens technically work too but they expire and are tied to a specific user; Internal Integration tokens are organization-scoped and the right shape for ZenSearch.

PagerDuty

1 agent tool for paging on-call from chat or non-SLA-breach automations. The SLA-breach paging path (AgentAutomationService.createSLAIncident) is a separate, automatic flow — this tool is the interactive one.

Tool	Description
create_pagerduty_incident	Create a new PagerDuty incident with a service identifier (PXXXXXX or schedule name), title, urgency, and optional details. Confirmation-gated on first use.

Service-ID resolution

PagerDuty's API takes a service ID (PXXXXXX). The tool accepts:

• The raw PXXXXXX identifier if the LLM knows it.
• A schedule name that maps to a service via the EW-5 on-call schedule sync (service_ownership rows).
• The team's sole schedule if exactly one exists — implicit.

Multi-schedule teams get an explicit ambiguity error naming the candidate schedules so the LLM can re-prompt the user.

Setup

PagerDuty credentials are shared with the on-call schedule sync (EW-5) — wire them once and both flows work. See the On-Call Routing operator runbook for the OAuth setup.

Risk tier

create_pagerduty_incident is T4 (irreversible side effect — the SMS / push / phone call cannot be unsent even if the incident object is later resolved). Different from create_servicenow_incident (T3 — reversible artifact, no out-of-band wakeup). Any future "page on-call / send alert" tool with the same out-of-band human-disruption side effect should also be T4 regardless of artifact reversibility.

Google Analytics

4 agent tools for querying Google Analytics 4 properties — pulling reports, listing properties, looking up realtime users, and discovering the metric / dimension catalogue (including custom dimensions your team has defined). Read-only — agents cannot create, modify, or delete anything in GA. Configure from Integrations → Google Analytics.

Tool	Description
list_ga4_properties	List every GA4 property the connected user has access to, grouped by parent account. Returns property IDs and display names; agents typically call this first to pick the right property for the question's context.
list_ga4_metrics_dimensions	Fetch the metric + dimension catalogue for one property, including custom definitions. Use before run_ga4_report when unsure which API names are valid — especially on properties with custom event tracking.
run_ga4_report	Core GA4 Data API query — pivot a property's data along dimensions (country, page_path, deviceCategory, ...) measured by metrics (activeUsers, sessions, screenPageViews, ...). Supports top-N ordering by a metric; date range defaults to the last 30 days.
run_ga4_realtime_report	Last-30-minutes realtime report. Use for live user counts and recently-fired events; a subset of dimensions / metrics is available compared to run_ga4_report.

Setup

1. In the Google Cloud Console → APIs & Services → Credentials, create an OAuth client ID (Application type: Web application). The Authorized redirect URI is shown in your platform admin's OAuth Clients → Google Analytics card; paste that exact value.
2. Under APIs & Services → Library, enable the Google Analytics Data API and the Google Analytics Admin API. Both are required — the Data API powers run_ga4_report / run_ga4_realtime_report; the Admin API powers list_ga4_properties / list_ga4_metrics_dimensions.
3. Your platform admin pastes the OAuth client ID + secret into Admin → OAuth Clients → Google Analytics. Server hot-reloads within 30 s.
4. In ZenSearch: open Integrations → Google Analytics and click Connect with Google. Authorize the requested scope (analytics.readonly) — agents will only ever read.
5. Each user repeats step 4 to grant access from their own Google account. The agent uses the invoking user's grant for every query, so an agent run sees exactly the properties that user has access to.

Auth model (per-user OAuth)

Google Analytics uses per-user OAuth — every user authorizes their own GA properties. A chat that needs a GA tool pauses with a "Connect Google Analytics" card the first time, then resumes after the user completes consent. This differs from Datadog (shared team credentials) and matches the pattern used for HubSpot, Salesforce, and Atlassian: GA properties have user-scoped access controls, so a single shared key would either over-share (every member sees every property) or under-share (only what the configuring admin sees).

Notes

• Per-property access in GA itself: the OAuth user must have Viewer or higher on each GA4 property they want the agent to read. list_ga4_properties returns only what the connected user can see.
• Quotas: GA Data API has project-wide quotas (default 200 queries/minute/property, 25k/day) plus per-user concurrency limits. Heavy agent usage on a small property can hit these; bump the quota in the Cloud Console if you see 429s.
• Read-only by design: there are no create_ga4_audience / update_ga4_property tools today. Write operations would require the analytics.edit scope and a different threat-model review before shipping.

Mixpanel

4 agent tools for querying Mixpanel product analytics — event listing, segmentation, funnels, and retention cohorts. Read-only — agents cannot send / modify / delete events. Configure from Integrations → Mixpanel.

Tool	Description
list_mixpanel_events	Enumerate event names tracked in the connected project. Call FIRST when unsure which event the user means — Mixpanel event names are team-specific (e.g. Signed Up vs User Signed Up vs signup), and a hallucinated name returns zero results silently.
query_mixpanel_segmentation	Count occurrences of an event over a date range, optionally segmented by a property (e.g. properties["plan"]). The core Mixpanel query — "how many sign-ups per day in May?", "sessions by browser last week", "DAU by plan tier".
query_mixpanel_funnel	Run a SAVED Mixpanel funnel by numeric ID over a date range. Returns per-date conversion analysis. Mixpanel's Query API does NOT support ad-hoc funnel construction — the team must have created the funnel in Mixpanel's UI; the agent looks up the funnel_id from the URL.
query_mixpanel_retention	Cohort retention — "of users who did X on day N, how many did Y on day N+1, N+7, N+30?". Default retention_type=birth uses each user's FIRST occurrence of born_event as their cohort anchor.

Auth model (Service Account credentials, no OAuth)

Mixpanel does NOT expose OAuth for the Query API. Instead, each user creates a Mixpanel Service Account under their Organization Settings and enters the username + secret in ZenSearch's Settings panel. Credentials are stored encrypted at rest (AES-GCM via CREDENTIAL_ENCRYPTION_KEY).

This differs from GA / HubSpot / Salesforce (per-user OAuth) and from Datadog / Sentry (shared team credentials): every Mixpanel user enters their own Service Account, project-scoped, validated against Mixpanel's /events/names endpoint at save time so typos catch immediately rather than on the first agent run.

Setup

1. In Mixpanel: Organization Settings → Service Accounts → Create. Pick a descriptive name (e.g. zensearch-agent-<your-email>) and grant the projects you want the agent to query. Mixpanel shows the username + secret in a one-time dialog — copy both before dismissing.
2. In Mixpanel: open Project Settings and copy the numeric Project ID (visible in the URL too).
3. In ZenSearch: open Integrations → Mixpanel.
4. Paste the Service Account username, secret, and project_id. Pick your region (US for mixpanel.com, EU for eu.mixpanel.com).
5. Click Save credentials. ZenSearch validates the credentials against Mixpanel's events/names endpoint before persisting — a typo surfaces here as a clean error, not on the first agent run.
6. Every user repeats steps 1–5 to grant the agent access from their own account.

Notes

• Per-project scope: each credential row binds to one Mixpanel project. Users with access to multiple projects need to create one credential per project (Settings UI to manage multiple per-user credential rows is a follow-up).
• Service Account permissions: the Service Account inherits the team-member's project role (Viewer / Analyst / Admin). Grant the minimum role that lets it read the events you care about — the Query API tools used here all work on Viewer-level access.
• No refresh path: Mixpanel Service Account credentials don't expire on their own. A 401 surfaces as an AuthRequired prompt asking the user to re-save (e.g. after manually rotating the secret in Mixpanel admin).
• Read-only by design: the Service Account can technically be used for write operations on Mixpanel's Ingestion API, but ZenSearch's agent tools only call the Query API. No track_mixpanel_event / set_user_profile tools today.

PostHog

6 agent tools for querying PostHog product analytics — dashboards, events, property definitions, and ad-hoc HogQL / insight / funnel queries. Read-only — agents cannot create or modify PostHog data. Configure from Integrations → PostHog.

Tool	Description
list_posthog_dashboards	List the project's dashboards so the agent can point the user at an existing saved view.
list_posthog_events	Enumerate recent events (with properties) — useful for sanity-checking what's being tracked.
list_posthog_property_definitions	List the project's event / person property definitions. Call when unsure which property name to filter or break down by.
query_posthog_hogql	Run an ad-hoc HogQL (SQL-like) query against the project — the most flexible tool for arbitrary analytics questions.
query_posthog_insight	Run a saved insight by ID over a date range and return its result series.
query_posthog_funnel	Run a funnel query and return per-step conversion.

Auth model (OAuth or Personal API Key)

PostHog supports two auth paths on the same per-user credential, picked by deployment:

• OAuth (Cloud) — for PostHog Cloud (us.posthog.com / eu.posthog.com). This is a PKCE public-client flow with Dynamic Client Registration; PostHog rotates the refresh token on every refresh, so ZenSearch persists the new token before retrying.
• Personal API Key (PAT) — for self-hosted PostHog (or Cloud users who prefer manual key management). PATs don't expire on their own; a 401 surfaces as an AuthRequired prompt to re-save.

Self-hosted hosts

Self-hosted PostHog base URLs are SSRF-gated by a composed allowlist: operator env (POSTHOG_ALLOWED_HOSTS) plus per-team admin-managed rows. Add your host on the Integrations → PostHog Settings panel (team admins only) before connecting. Credentials are validated against PostHog at save time so typos surface immediately rather than on the first agent run. See OAuth Clients for registering the OAuth client.

Web Search

The web_search tool lets agents query the public web when an answer cannot be found in your indexed knowledge. Two backends are supported:

Backend	Best for
DuckDuckGo	Default. No configuration required; uses public HTML scraping. Suitable for low-volume use.
SearXNG	Self-hosted metasearch instance that aggregates Google, Bing, Brave, and 70+ other engines under a single endpoint. Better for higher volume, less rate-limited, no third-party dependency.

To use SearXNG, deploy a SearXNG instance reachable from your ZenSearch deployment and point the agent's web search backend at its base URL. Falls back to DuckDuckGo if the configured backend is unreachable.

The tool returns title + URL + snippet for each result; agents typically follow up with a fetch tool or by ingesting the page into a collection for citation-grounded use.

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

1. Navigate to Settings > Integrations > Custom Tools
2. Click Create Tool
3. 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:

1. The agent provides parameter values based on the JSON schema
2. ZenSearch sends an HTTP request to the configured endpoint
3. The response body is returned to the agent as the tool result
4. 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

1. Navigate to Integrations → MCP Servers (/integrations/mcp)
2. Click Add Server
3. Provide the server URL and authentication details
4. ZenSearch discovers available tools automatically
5. Enable the tools you want agents to use

Supported Transports

• SSE (sse): Server-sent events over HTTP — the default, usable in any deployment.
• Streamable HTTP (streamable_http): URL-based streaming transport — usable in any deployment (SSRF / egress-gated like custom webhooks).
• Stdio (stdio): Local subprocess communication — self-hosted only, gated behind MCP_STDIO_ENABLED (and the optional MCP_STDIO_ALLOWED_COMMANDS allowlist).

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)

Resources and prompts

Beyond the tools an MCP server exposes, ZenSearch can also read its resources (files, records, or documents addressable by URI) and render its prompt templates. Four generic, read-only tools cover this — they are available to the agent automatically whenever your team has at least one usable MCP server connected (a server whose transport is enabled — sse and streamable_http are always usable; stdio only when MCP_STDIO_ENABLED is on). Teams with no MCP server see none of these tools.

Tool	What it does
list_mcp_resources	Lists the read-only resources (files, records, documents addressable by URI) exposed by the team's connected MCP servers. Optionally filter to one server by name.
read_mcp_resource	Reads the content of a specific resource by URI from a named server.
list_mcp_prompts	Lists the prompt templates (and their arguments) exposed by the team's connected MCP servers. Optionally filter to one server by name.
get_mcp_prompt	Renders a prompt template from a named server with the given arguments, returning its messages.

How they behave:

• Read-only, risk tier T0 — no approval is ever required to call them.
• Server identified by name — read_mcp_resource and get_mcp_prompt take the target MCP server's name as a parameter (matched case-insensitively against the server's name or display name); the two list_* tools accept an optional server filter and otherwise aggregate across every connected server.
• Connect on demand — each call opens a fresh session to the relevant server(s) and closes it when done. There is no separate discovery step, cache, or migration to run.
• Graceful capability skipping — a server that doesn't support the resources or prompts capability is simply skipped during aggregation rather than failing the whole call.
• Egress-gated — for URL transports, the same SSRF/egress policy applied to custom webhooks governs these connections.

Managing Integrations

Enabling Tools per Agent

Each agent can be configured with a specific set of integration tools:

1. Edit the agent configuration
2. In the Tools section, browse available integration tools
3. Enable or disable individual tools
4. 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