{"slug":"connector-panel","category":"permissions","job":"steer","added":"2026-09-15T20:37Z","title":"Connector Panel","description":"A settings panel for connecting an app or MCP server — shows capabilities overview, groups tools by type, and lets users set per-tool permission levels.","url":"https://ai-patterns.app/patterns/permissions/connector-panel","markdown":"https://ai-patterns.app/patterns/permissions/connector-panel.md","json":"https://ai-patterns.app/api/patterns/permissions/connector-panel","seenIn":[{"team":"Claude","source":"https://support.claude.com/en/articles/11176164"},{"team":"chatgpt","source":"https://developers.openai.com/api/docs/guides/developer-mode"},{"team":"Intercom","source":"https://www.intercom.com/help/en/articles/11461635-add-mcp-connectors-for-popular-apps-or-custom-mcps"},{"team":"Perplexity","source":"https://www.perplexity.ai/help-center/en/collections/18799295-connectors-integrations"}],"spec":"# Connector Panel\n\n## Summary\nA structured settings panel for connecting and configuring an external app or MCP server with an AI agent. It shows what the integration can do (overview bullets and links in a sidebar), lists every tool the integration exposes grouped by capability, and lets users set per-tool or per-group permission levels — Disable, Always ask, or Allow — without leaving the panel. The header carries the app identity (name, verified badge) and an Add connector CTA; a sidebar holds discovery content; the main column offers search and group filtering over the tool list.\n\n## When to use\n- When onboarding a new MCP server or reviewing an existing integration's permissions before activating it.\n- When users need to browse what an integration can do and control exactly which tools it may run autonomously, run after confirmation, or never run.\n- In an agent settings area, marketplace, or connector catalog — not inline in an agent chat transcript.\n\n## When not to use\n- For in-transcript per-call approval (one tool, one moment) — use Tool Approval instead. This panel manages standing permissions, not live prompts.\n- As a generic settings form or feature-flag manager unrelated to agent tool permissions.\n- When the integration exposes only one or two tools — a simple toggle row suffices; the full panel layout is only worth its overhead at five or more tools.\n\n## Anatomy\n- **Header**: app icon, name, verified badge (if publisher-verified), one-line description, \"Add connector\" CTA, close button.\n- **Sidebar**: \"Overview\" section — a short bullet list of capabilities phrased from the user's perspective; \"Links\" section — anchor links to the app's website and documentation.\n- **Filter bar**: Group filter dropdown (All + each group name) and a text search that matches on tool name or description.\n- **Tool group section**: a collapsible label row showing the group name and a group-level \"Allow\" button that disappears once every tool in the group is allowed; below it, one tool row per tool.\n- **Tool row**: tool name, protocol badge (e.g. \"MCP\"), description, and a three-way permission toggle (Disable / Always ask / Allow).\n\n## Behavior\n- Search immediately filters tool rows by name or description substring across all groups.\n- The group dropdown constrains the visible groups; combining it with search narrows within that group.\n- The group-level \"Allow\" button sets every tool in the group to Allow in one action.\n- Per-tool permission is a mutually exclusive three-way toggle: only one of Disable, Always ask, Allow is active at a time.\n- Groups are individually collapsible; collapsing hides tool rows without changing their permissions.\n- The panel is layout-agnostic — it can be rendered as a modal (with a backdrop owned by the caller) or embedded directly in a settings page.\n\n## Content guidelines\n- Overview bullets phrase capabilities from the user's perspective: \"Access deployment logs for debugging\", not \"Provides log access\".\n- Tool names match the tool's identifier exactly — no paraphrasing.\n- Tool descriptions state what the tool does, not why the agent would use it (\"Generate a temporary shareable link…\", not \"Useful for sharing protected pages\").\n- The verified badge appears only when the publisher's identity has been confirmed — don't use it as a general quality signal.\n- Protocol badges (\"MCP\") are short, literal, and uppercased.\n\n## Accessibility\n- The permission toggle group for each tool uses `role=\"group\"` with `aria-label` naming the tool (\"Permission for Check domain availability\").\n- Each permission button exposes its active state via `aria-pressed`.\n- The verified badge icon carries `aria-label=\"Verified\"` so it's not invisible to screen readers.\n- Group collapse buttons set `aria-expanded` to reflect the open/closed state.\n- The group filter dropdown follows the listbox disclosure pattern: `aria-haspopup=\"listbox\"`, `aria-expanded`, closes on Escape or outside click.\n- The search input has `aria-label=\"Search tools\"`.\n\n## Related patterns\n- **Tool Approval** — Use it as well for in-context permission on each call, while this panel manages standing permissions set beforehand.\n- **Memory Panel** — Use it as well when people also need to manage what the AI has learned about them, not just what it can read.\n- **Agent Triggers** — Use it as a layout reference, since it shares the sidebar overview plus main content shape.\n","code":"\"use client\";\n\nimport * as React from \"react\";\nimport { AnimatePresence, motion } from \"motion/react\";\nimport {\n BadgeCheck,\n ChevronDown,\n ExternalLink,\n Plus,\n Search,\n X,\n} from \"lucide-react\";\n\nimport { cn } from \"@/lib/utils\";\n\nexport type ToolPermission = \"allow\" | \"always-ask\" | \"disable\";\n\nexport interface ConnectorTool {\n id: string;\n name: string;\n description: string;\n badge?: string;\n permission: ToolPermission;\n}\n\nexport interface ConnectorToolGroup {\n id: string;\n label: string;\n tools: ConnectorTool[];\n}\n\nexport interface ConnectorLink {\n label: string;\n href: string;\n icon?: React.ComponentType<{ className?: string }>;\n}\n\nexport interface ConnectorPanelProps {\n appName: string;\n appDescription: string;\n appIcon?: React.ReactNode;\n verified?: boolean;\n overview?: string[];\n links?: ConnectorLink[];\n toolGroups: ConnectorToolGroup[];\n onAddConnector?: () => void;\n onClose?: () => void;\n onPermissionChange?: (toolId: string, permission: ToolPermission) => void;\n onGroupAllow?: (groupId: string) => void;\n className?: string;\n}\n\n// ─── Permission toggle ────────────────────────────────────────────────────────\n\nfunction PermissionToggle({\n value,\n onChange,\n toolName,\n}: {\n value: ToolPermission;\n onChange: (p: ToolPermission) => void;\n toolName: string;\n}) {\n const options: { value: ToolPermission; label: string }[] = [\n { value: \"disable\", label: \"Disable\" },\n { value: \"always-ask\", label: \"Always ask\" },\n { value: \"allow\", label: \"Allow\" },\n ];\n\n return (\n \n {options.map((opt) => (\n onChange(opt.value)}\n aria-pressed={value === opt.value}\n className={cn(\n \"rounded-md px-2.5 py-1 text-xs font-medium transition-colors\",\n value === opt.value\n ? \"bg-foreground text-background\"\n : \"text-muted-foreground hover:bg-accent hover:text-foreground\",\n )}\n >\n {opt.label}\n \n ))}\n \n );\n}\n\n// ─── Tool row ─────────────────────────────────────────────────────────────────\n\nfunction ToolRow({\n tool,\n onPermissionChange,\n}: {\n tool: ConnectorTool;\n onPermissionChange: (p: ToolPermission) => void;\n}) {\n return (\n
\n
\n
\n {tool.name}\n {tool.badge && (\n \n {tool.badge}\n \n )}\n
\n

\n {tool.description}\n

\n
\n \n
\n );\n}\n\n// ─── Tool group section ───────────────────────────────────────────────────────\n\nfunction ToolGroupSection({\n group,\n onPermissionChange,\n onGroupAllow,\n}: {\n group: ConnectorToolGroup & { tools: ConnectorTool[] };\n onPermissionChange: (toolId: string, p: ToolPermission) => void;\n onGroupAllow: (groupId: string) => void;\n}) {\n const [collapsed, setCollapsed] = React.useState(false);\n const allAllowed = group.tools.every((t) => t.permission === \"allow\");\n\n return (\n
\n
\n setCollapsed((c) => !c)}\n aria-expanded={!collapsed}\n className=\"flex flex-1 items-center gap-1 text-xs font-medium text-muted-foreground hover:text-foreground\"\n >\n \n {group.label}\n \n {!allAllowed && (\n onGroupAllow(group.id)}\n className=\"rounded-md bg-foreground px-2.5 py-1 text-xs font-medium text-background transition-opacity hover:opacity-80\"\n >\n Allow\n \n )}\n
\n\n \n {!collapsed && (\n \n {group.tools.map((tool) => (\n onPermissionChange(tool.id, p)}\n />\n ))}\n \n )}\n \n
\n );\n}\n\n// ─── Filter bar ───────────────────────────────────────────────────────────────\n\nfunction FilterBar({\n groups,\n activeGroup,\n onGroupChange,\n query,\n onQueryChange,\n}: {\n groups: ConnectorToolGroup[];\n activeGroup: string | null;\n onGroupChange: (id: string | null) => void;\n query: string;\n onQueryChange: (q: string) => void;\n}) {\n const [dropOpen, setDropOpen] = React.useState(false);\n const dropRef = React.useRef(null);\n\n React.useEffect(() => {\n if (!dropOpen) return;\n function handle(e: MouseEvent) {\n if (!dropRef.current?.contains(e.target as Node)) setDropOpen(false);\n }\n document.addEventListener(\"mousedown\", handle);\n return () => document.removeEventListener(\"mousedown\", handle);\n }, [dropOpen]);\n\n const currentLabel =\n groups.find((g) => g.id === activeGroup)?.label ?? \"All\";\n\n return (\n
\n
\n setDropOpen((o) => !o)}\n aria-haspopup=\"listbox\"\n aria-expanded={dropOpen}\n className=\"inline-flex items-center gap-1 rounded-md border px-2.5 py-1.5 text-xs font-medium transition-colors hover:bg-accent\"\n >\n {currentLabel}\n \n \n\n \n {dropOpen && (\n \n
  • \n {\n onGroupChange(null);\n setDropOpen(false);\n }}\n className={cn(\n \"w-full px-3 py-2 text-left text-xs transition-colors hover:bg-accent\",\n activeGroup === null && \"font-semibold\",\n )}\n >\n All\n \n
    • \n {groups.map((g) => (\n
  • \n {\n onGroupChange(g.id);\n setDropOpen(false);\n }}\n className={cn(\n \"w-full px-3 py-2 text-left text-xs transition-colors hover:bg-accent\",\n activeGroup === g.id && \"font-semibold\",\n )}\n >\n {g.label}\n \n
    • \n ))}\n \n )}\n     \n
    \n\n
    \n \n onQueryChange(e.target.value)}\n placeholder=\"Search tools\"\n aria-label=\"Search tools\"\n className=\"w-full rounded-md border bg-background py-1.5 pl-8 pr-3 text-xs placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring\"\n />\n
    \n
    \n );\n}\n\n// ─── Main export ──────────────────────────────────────────────────────────────\n\nexport function ConnectorPanel({\n appName,\n appDescription,\n appIcon,\n verified = false,\n overview = [],\n links = [],\n toolGroups: initialGroups,\n onAddConnector,\n onClose,\n onPermissionChange,\n onGroupAllow,\n className,\n}: ConnectorPanelProps) {\n const [toolGroups, setToolGroups] = React.useState(initialGroups);\n const [query, setQuery] = React.useState(\"\");\n const [activeGroup, setActiveGroup] = React.useState(null);\n\n function handlePermissionChange(toolId: string, permission: ToolPermission) {\n setToolGroups((prev) =>\n prev.map((group) => ({\n ...group,\n tools: group.tools.map((t) =>\n t.id === toolId ? { ...t, permission } : t,\n ),\n })),\n );\n onPermissionChange?.(toolId, permission);\n }\n\n function handleGroupAllow(groupId: string) {\n setToolGroups((prev) =>\n prev.map((group) =>\n group.id === groupId\n ? {\n ...group,\n tools: group.tools.map((t) => ({\n ...t,\n permission: \"allow\" as ToolPermission,\n })),\n }\n : group,\n ),\n );\n onGroupAllow?.(groupId);\n }\n\n const filteredGroups = toolGroups\n .filter((g) => !activeGroup || g.id === activeGroup)\n .map((g) => ({\n ...g,\n tools: g.tools.filter(\n (t) =>\n !query ||\n t.name.toLowerCase().includes(query.toLowerCase()) ||\n t.description.toLowerCase().includes(query.toLowerCase()),\n ),\n }))\n .filter((g) => g.tools.length > 0);\n\n return (\n \n {/* Header */}\n
    \n {appIcon && (\n
    \n {appIcon}\n
    \n )}\n
    \n
    \n {appName}\n {verified && (\n \n )}\n
    \n

    \n {appDescription}\n

    \n
    \n
    \n \n \n Add connector\n \n {onClose && (\n \n \n \n )}\n
    \n
    \n\n {/* Body */}\n
    \n {/* Sidebar */}\n \n {overview.length > 0 && (\n
    \n

    \n Overview\n

    \n
      \n {overview.map((item, i) => (\n
    • \n \n \n {item}\n \n
      • \n ))}\n
    \n
    \n )}\n\n {links.length > 0 && (\n
    \n

    \n Links\n

    \n
      \n {links.map((link, i) => {\n const Icon = link.icon ?? ExternalLink;\n return (\n
    • \n \n \n {link.label}\n \n
      • \n );\n })}\n
    \n
    \n )}\n \n\n {/* Tools column */}\n
    \n
    \n

    Tools

    \n
    \n\n \n\n
    \n {filteredGroups.length === 0 ? (\n

    \n No tools match your search.\n

    \n ) : (\n filteredGroups.map((group) => (\n \n ))\n )}\n
    \n
    \n
    \n \n );\n}\n","dependencies":["lucide-react","motion"],"localImports":["@/lib/utils"]}