mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
017d7c7377
* fix: reduce Vale false positives via vocab and config updates - Make English-word vocab entries case-insensitive so sentence-start capitalization and normal prose usage stop flagging (agents, rest, cursor, setup, endpoints, etc.) - Add vocab entries for filenames and code identifiers that appear in frontmatter and JSX contexts (docs.json, llms.txt, CLAUDE.md, etc.) - Ignore openapi frontmatter lines, filenames, JSX attributes, email addresses, and internal link targets via TokenIgnores - Skip inline code scope and indented code fences - Add Headings exceptions for proper nouns (Claude Code, GitHub Actions, Route 53, GA4, etc.) - Disable linting for the all-code vercel-json-generator snippet Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: resolve all Vale warnings and errors across docs Content fixes: - Reword sentences using 'will', first person, spaced em dashes, 'e.g.', Latin abbreviations, and hyphenated adverbs - Sentence-case headings that started with dotted filenames - Backtick literal API values instead of bolding them - Move periods inside quotation marks - Fix Oxford comma rule misfires by restructuring sentences False-positive suppression: - Vale toggles around example user questions, keyboard shortcut keys (Cmd+I), UI labels, and code samples in JSX contexts that Vale misparses - Exclude vale toggle comments from the brace Token/BlockIgnores so in-document commands actually reach Vale (the greedy brace pattern was also silently swallowing large regions; now lazy) - Vocab entries for code identifiers (internal_id, handleSubmit, etc.) - Per-file rule disables for component docs with dotted JSX names and files where link-target linting ignores in-document toggles Result: vale --minAlertLevel warning is clean repo-wide; only suggestion-level items (Passive, Semicolons, Acronyms) remain. mint broken-links passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: correct WordList rule instead of degrading prose - Restore sentence-start "Email" in advanced-support; the rule now only flags hyphenated e-mail/E-mail forms - Restore the idiom "above all else"; the above->preceding swap now exempts "above all" Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: restore deliberate prose flagged by blunt rules - Restore spatial 'above the navbar' / 'above a page title' in custom-scripts; the above->preceding swap now exempts 'above the/a/an' - Restore the '= ...' in the react-components named-export example (the ellipsis is inside inline code) with an Ellipses toggle - Restore SLA phrasing 'will use commercially reasonable efforts' with a Will toggle - Restore the quoted developer question in the GEO guide intro with a FirstPerson toggle, matching the file's other example questions Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: remove WordList swaps that flag legitimate English - Drop tablet->device and firewalls->firewall rules; both words are correct in ordinary prose - Narrow touch->tap to UI-instruction phrasing (touch the/a) so 'keep in touch' and 'touch devices' stop flagging Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: reposition vale toggles to wrap whole blocks Toggle comments placed between list items split the lists (restarting ol numbering in deployments) and comments flush against tables risked breaking GFM table parsing. Wrap entire lists/tables with blank-line separation instead. Verified rendering with mint dev: single ol with two items, tables intact, no comments in visible DOM. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * refactor: prune accept.txt to load-bearing entries Empirically removed 166 vocab entries (575 -> 409) whose removal causes no Vale flags across all 908 English pages: dictionary words that never needed listing (agents, setup, endpoints, webhooks, yaml), lowercase entries the speller already accepts, and filename entries made redundant by inline vale toggles. Kept every case-enforcing entry (API, JSON, GitHub, ...) so casing policy is unchanged, plus entries that double as capitalization exceptions for headings (mcp, md, auth, cursor, txt). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Update ai/mintlify-mcp.mdx * Update api/agent/v2/create-agent-job.mdx * chore: alphabetize Headings exceptions and accept.txt Case-insensitive sort, ignoring the (?i) prefix; also drops a duplicate Scala entry. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix: re-apply OxfordComma rewrite lost in branch merge Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: resolve Vale suggestions batch 1 (acronyms, semicolons, passive voice) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: resolve remaining Vale suggestions (passive voice batch 2) Rewrite ~90 passive constructions to active voice across deploy, guides, migration-services, and organize docs. Toggle the deliberate passive examples in the style-and-tone guide ('by zombies' test). Add axios/lodash vocab entries for a repositioned code example. vale . is now fully clean: 0 errors, 0 warnings, 0 suggestions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
114 lines
6.8 KiB
Plaintext
114 lines
6.8 KiB
Plaintext
---
|
|
title: "Agent integrations"
|
|
description: "Connect Slack, Notion, Linear, Jira, Confluence, and other apps so the agent can pull live context when answering questions and updating content."
|
|
keywords: ["integrations", "Slack", "Notion", "Linear", "Jira", "Confluence", "Salesforce", "Intercom", "Google Calendar", "Google Drive", "HubSpot", "Plain", "context", "Nango"]
|
|
---
|
|
|
|
Agent integrations give the agent access to context from other tools that your team uses. Once connected, the agent can search Slack threads, read Notion pages, look up Linear issues, and pull context from other apps to inform its responses and content updates.
|
|
|
|
## Connection scope
|
|
|
|
Integrations connect in one of two ways:
|
|
|
|
- **Shared integrations** connect once for your entire organization. Anyone on the team can prompt the agent to use them. Slack, Notion, Linear, Jira, Confluence, Salesforce, Intercom, HubSpot, and Plain all connect this way.
|
|
- **Personal integrations** connect per user. Each teammate authorizes their own account, and the agent can only use a personal integration on behalf of the user who connected it. Google Calendar and Google Drive are personal.
|
|
|
|
Personal integrations keep user-specific data, like calendar events, scoped to the user who connected the integration instead of shared across the organization.
|
|
|
|
## Connect an integration
|
|
|
|
Admins and editors can connect shared integrations on behalf of the organization.
|
|
|
|
1. Go to the [Agent integrations](https://app.mintlify.com/settings/organization/integrations) page in your dashboard.
|
|
2. Find the integration you want to connect.
|
|
3. Click **Connect**.
|
|
4. Follow the OAuth prompts to authorize Mintlify to access your account.
|
|
|
|
Some integrations open an additional configuration step before the connection completes. Jira, Confluence, and Salesforce ask for your workspace URL or subdomain before the OAuth flow begins, and API-key providers like Plain prompt you to paste an API key.
|
|
|
|
## Supported integrations
|
|
|
|
| Integration | Scope |
|
|
| --- | --- |
|
|
| Confluence | Shared |
|
|
| Google Calendar | Personal |
|
|
| Google Drive | Personal |
|
|
| HubSpot | Shared |
|
|
| Intercom | Shared |
|
|
| Jira | Shared |
|
|
| Linear | Shared |
|
|
| Notion | Shared |
|
|
| Plain | Shared |
|
|
| Salesforce | Shared |
|
|
| Slack | Shared |
|
|
|
|
## How the agent uses integrations
|
|
|
|
The agent uses connected integrations as tools. When you ask the agent a question or give it a task, it can search and retrieve content from your connected apps to build context.
|
|
|
|
For example:
|
|
- "Summarize the Slack thread about the v2 API migration and write it up for the knowledge base."
|
|
- "Check the Linear ticket for this feature and document the behavior."
|
|
- "What did the team decide about rate limiting? Check Slack."
|
|
|
|
The agent only accesses integration data when it's relevant to the request. It does not proactively read from connected apps.
|
|
|
|
## Permissions and access
|
|
|
|
Each integration requests the OAuth scopes or API-key permissions it needs to search and retrieve content from the connected app. Mintlify requests read-only scopes wherever the provider offers them.
|
|
|
|
Review the exact scopes during the OAuth consent screen before authorizing the connection. The consent screen lists every permission the agent receives, and you can revoke the connection at any time from the dashboard or from the connected app's own integrations settings.
|
|
|
|
If your organization restricts which apps users can authorize, ask the relevant admin (such as your Slack or Google Workspace admin) to allow the Mintlify integration before connecting.
|
|
|
|
### What the agent can read from each app
|
|
|
|
The agent inherits the access of the account that authorized the connection. It can only read content that the authorizing user (for personal integrations) or the connected workspace account (for shared integrations) already has access to in the source app.
|
|
|
|
| Integration | Content the agent can access |
|
|
| --- | --- |
|
|
| Confluence | Pages and attachments in spaces the connected account can read |
|
|
| Google Calendar | Events on calendars the connected user can view |
|
|
| Google Drive | Files and folders the connected user can view, including shared drives |
|
|
| HubSpot | CRM records (contacts, companies, deals, tickets) the connected account can read |
|
|
| Intercom | Conversations, contacts, and help center articles the connected account can read |
|
|
| Jira | Issues and comments in projects the connected account can read |
|
|
| Linear | Issues, projects, and comments in teams the connected account can read |
|
|
| Notion | Pages and databases explicitly shared with the Mintlify integration |
|
|
| Plain | Threads and customer records accessible with the provided API key |
|
|
| Salesforce | Standard and custom objects the connected account can read |
|
|
| Slack | Public channels the workspace grants access to, plus private channels you add the Mintlify app to |
|
|
|
|
To narrow what the agent can see, restrict the connected account's permissions in the source app. For example, invite the Mintlify Slack app only to specific channels, or share only selected Notion pages with the integration.
|
|
|
|
## Data retention after disconnect
|
|
|
|
When you disconnect an integration, the agent immediately loses the ability to read from that app. Mintlify doesn't retain a durable copy of integration content. The agent fetches data on each request through the live OAuth token or API key, so disconnecting cuts off future access.
|
|
|
|
Content that appeared in past agent responses or pull requests stays in place (chat transcripts, published pages, PR history). Edit or delete the pages and conversations directly if you also want that content removed.
|
|
|
|
## Troubleshoot a failed connection
|
|
|
|
If an integration stops working or shows an error in the dashboard, the underlying OAuth token usually expired, the connected app revoked it, or its required scopes changed.
|
|
|
|
To restore access:
|
|
|
|
1. Go to the [Agent integrations](https://app.mintlify.com/settings/organization/integrations) page in your dashboard.
|
|
2. Find the affected integration and click **Configure**.
|
|
3. Click **Disconnect**.
|
|
4. Click **Connect**.
|
|
5. Complete the OAuth flow.
|
|
|
|
For API-key providers like Plain, generate a new API key in the source app and paste it into the integration's configuration. If the agent still can't access data after reconnecting, confirm that the authorizing user has permission to view the relevant content in the source app.
|
|
|
|
## Disconnect an integration
|
|
|
|
1. Go to the [Agent integrations](https://app.mintlify.com/settings/organization/integrations) page in your dashboard.
|
|
2. Find the connected integration you want to disconnect.
|
|
3. Click **Configure**.
|
|
4. Click **Disconnect**.
|
|
|
|
Disconnecting a shared integration removes it for everyone in your organization, and the agent immediately loses access to that tool.
|
|
|
|
Disconnecting a personal integration only removes your own connection. Other teammates who have connected the same integration keep their access, and the agent can still use the integration on their behalf.
|