API VEGA

Model Context Protocol (MCP)

Узнайте, как использовать Model Context Protocol (MCP), чтобы обеспечить безопасный доступ ИИ-агентов к вашим данным Intercom и взаимодействие с ними там, где это полезно.

Доступность регионов

В настоящее время сервер Intercom MCP поддерживается только в рабочих пространствах, размещённых в США.

Что такое Model Context Protocol?

MCP — это протокол, который позволяет инструментам и приложениям AI подключаться к данным и сервисам Intercom безопасным, стандартизированным способом. Он обеспечивает структурированный подход к действиям моделей AI:

  • находить и извлекать данные Intercom (разговоры, контакты и т. п.)

  • получать доступ к конкретным инструментам и функциональности, предоставляемой Intercom

  • сохранять контекст вашего рабочего пространства Intercom при работе с помощниками AI

Как работает MCP

Intercom размещает удалённый сервер MCP, который следует за аутентифицированной удалённой спецификацией MCP (документацию). Этот сервер обрабатывает запросы от инструментов AI и предоставляет доступ к данным Intercom через безопасный интерфейс.

URL-адреса подключения:

  • Streamable HTTP (рекомендуется): https://mcp.intercom.com/mcp

  • Legacy SSE: https://mcp.intercom.com/sse (устаревшее, поддерживается для обратной совместимости)

Когда инструмент или приложение нуждается в доступе к данным Intercom:

  • инструмент подключается к серверу MCP Intercom

  • Аутентификация проверяет разрешения пользователя

  • затем инструмент может получить доступ к соответствующим данным и функциональности Intercom

  • соединение остаётся активным для получения обновлений по мере необходимости

Преимущества использования MCP

  • Безопасный доступ: весь доступ к данным аутентифицирован и авторизован

  • Стандартизированный интерфейс: последовательный шаблон взаимодействия для разных инструментов AI

  • Контекстуальное понимание: помощники AI mantienen осведомлённость о вашем окружении Intercom

  • Повышение эффективности разработки: извлекайте и интерпретируйте данные клиентов Intercom через ваши внутренние AI-инструменты, чтобы работать эффективнее

Доступные инструменты

Сервер Intercom MCP предоставляет 6 инструментов для взаимодействия с API Intercom:

Универсальные инструменты

search

Универсальный инструмент поиска для нахождения разговоров и контактов с использованием DSL-запросов.

Ключевые особенности:

  • Необходимо указать object_type:conversations или object_type:contacts для указания, к какому API выполнить вызов

  • Поддерживает сложные запросы по полям с операторами (eq, neq, gt, lt, contains и т. д.)

  • Возвращает сводные результаты с ID, начинающимися с типа (conversation_* или contact_*)

  • Встроенная поддержка пагинации с параметром starting_after

  • Возможность полнотекстового поиска с параметром q:

Примеры запросов:

object_type:conversations state:open source_type:email
object_type:contacts email_domain:"example.com"
object_type:conversations source_body:contains:"refund" limit:20
fetch

Получение полной детализированной информации для конкретных ресурсов.

Ключевые особенности:

  • Используйте ID, возвращённые в результатах поиска (с префиксом conversation_ или contact_)

  • Возвращает полные детали ресурса, включая метаданные, части разговора, кастомные атрибуты

  • Включает прямые ссылки на Intercom app для удобной навигации

Прямые инструменты API

search_conversations

Поиск разговоров по конкретным IDs с расширенными фильтрами, включая источник, детали автора, статус и временные статистики.

get_conversation

Получение одного разговора по ID с полными деталями, включая все части разговора и метаданные.

search_contacts

Поиск контактов по IDs, имени, email, телефону, кастомным атрибутам или домену email с гибкими схемами сопоставления.

get_contact

Получение полной информации о контакте, включая кастомные атрибуты, данные о местоположении и временные метки активности.

Настройка

Методы аутентификации

Сервер MCP поддерживает два подхода к аутентификации:

  • OAuth Flow (рекомендуется): автоматическая аутентификация через браузер

  • Bearer Token: аутентификация с использованием Bearer API-токена

Примеры конфигурации

Руководство по конфигурации

Ниже приведённые примеры являются общими шаблонами. Всегда обращайтесь к официальной документации вашего поставщика LLM для получения самых актуальных инструкций по конфигурации, так как детали настройки могут варьироваться между версиями и провайдерами.

Для OAuth authentication (рекомендуется):

{
  "mcpServers": {
    "intercom": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.intercom.com/mcp"
      ]
    }
  }
}

Для Bearer token authentication:

{
  "mcpServers": {
    "intercom": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.intercom.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_INTERCOM_API_TOKEN"
      }
    }
  }
}

Руководства по настройке LLM-поставщиков

У каждого поставщика AI есть свои инструкции по настройке серверов MCP. Обратитесь к официальной документации вашего провайдера:

Необходимые разрешения

Сервер Intercom MCP требует следующие разрешения для доступа к данным вашего workspace. При использовании аутентификации Bearer token убедитесь, что ваш токен доступа включает эти области. Подробнее об OAuth-разрешениях.

  • Read and list users and companies: Требуется для доступа к данным пользователей и компаний Intercom

  • Read conversations: Требуется для доступа к данным Intercom Conversation

MCP Inspector для исследования сервера

Проверьте соединение с помощью:

npx @modelcontextprotocol/inspector

Затем подключитесь к:

  • Transport Type: Streamable HTTP

  • URL: https://mcp.intercom.com/mcp (или /sse для legacy)

Отладка и устранение неполадок MCP-Remote

  • Проблемы с аутентификацией
# Завершить существующие соединения
pkill -f mcp-remote

# Очистить кэш аутентификации MCP
rm -rf ~/.mcp-auth
  • Проверка соединения
# Прямая проверка подключения
npx mcp-remote https://mcp.intercom.com/mcp

# С bearer токеном
npx mcp-remote https://mcp.intercom.com/mcp --header "Authorization:Bearer YOUR_TOKEN"
  • Просмотр активных соединений MCP
ps aux | grep mcp-remote | grep -v grep

Обработка ошибок

  • Invalid queries: инструмент поиска валидирует имена полей и операторы, возвращая конкретные сообщения об ошибках

  • Authentication failures: проверьте валидность токена или перезапустите OAuth flow

  • Rate limiting: применяются лимиты Intercom API — при необходимости уменьшите частоту запросов

Советы по устранению неполадок

  • Перезапустите AI Agent после изменений конфигурации

  • Используйте MCP Inspector для проверки доступности инструментов

  • Проверьте консоль браузера на наличие ошибок, связанных с OAuth

  • Убедитесь в разрешениях Intercom API для bearer auth