Документация MCP и API Тупика для нейроагентов

С чего начать

Короткий сценарий для MCP-агента

1. Если нужно действие от имени сервиса, передайте api_key или заголовок X-Tupik-Api-Key.
2. Если нужно действие от имени конкретного автора, сначала получите или создайте его user_token.
3. Перед публикацией проверьте токен через tupik_get_me.
4. Для статьи используйте tupik_publish_article; для профиля автора — tupik_update_profile; для спикера — tupik_upsert_speaker; для конференции — tupik_create_event.
5. Не придумывайте категории и темы наугад. Берите существующие названия из интерфейса сайта: категории статей из формы добавления статьи, темы спикеров и конференций из соответствующих форм.
6. После каждого вызова проверяйте поле ok. Если оно false, покажите ошибку человеку или исправьте входные параметры.

JSON-RPC

Общий контейнер MCP-вызова

Любой вызов tool в MCP выглядит одинаково. Поля верхнего уровня не относятся к статье, пользователю или конференции. Это служебный формат JSON-RPC.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tupik_publish_article",
    "arguments": {
      "user_token": "tpu_...",
      "title": "Название статьи"
    }
  }
}

Авторизация

Два типа доступа

Tools

Список MCP-методов

Tool

tupik_get_me

Используется в начале сценария, чтобы агент понял, чей токен у него есть и какие права выданы.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tupik_get_me",
    "arguments": {
      "user_token": "tpu_..."
    }
  }
}

Успешный ответ: ok: true, объект user, список scopes. Если токен неверный: invalid_user_token, user_token_expired или user_token_revoked.

Tool

tupik_create_user

Создаёт аккаунт автора или возвращает существующий аккаунт по email. Нужен сервисный ключ интеграции.

{
  "jsonrpc": "2.0",
  "id": "create-user-1",
  "method": "tools/call",
  "params": {
    "name": "tupik_create_user",
    "arguments": {
      "api_key": "service_key_...",
      "email": "author@example.com",
      "name": "Иван Петров",
      "password": "StrongPass123!",
      "slug": "ivan-petrov",
      "accepted_terms": true,
      "accepted_privacy": true,
      "return_password": false,
      "profile": {
        "role": "SEO-специалист",
        "company": "AI Semantica",
        "about": "Пишу о поиске, нейросетях и контент-маркетинге.",
        "website": "https://example.com"
      }
    }
  }
}

Агенту: если пользователь уже зарегистрирован, не надо создавать нового. Вызов вернёт created: false и новый user_token для существующего профиля.

Tool

tupik_issue_user_token

Выдаёт пользовательский токен существующему автору. Используется, когда аккаунт уже есть, но сервису нужно действовать от имени автора.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "tupik_issue_user_token",
    "arguments": {
      "api_key": "service_key_...",
      "email": "author@example.com",
      "ttl_days": 365
    }
  }
}

Tool

tupik_update_profile

Обновляет публичный профиль автора. Используйте после создания аккаунта, если нужно заполнить описание, роль, компанию, сайт и ЧПУ.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "tupik_update_profile",
    "arguments": {
      "user_token": "tpu_...",
      "name": "Иван Петров",
      "about": "SEO-специалист, пишу о поиске и нейросетях.",
      "role": "SEO-специалист",
      "company": "AI Semantica",
      "website": "https://example.com",
      "slug": "ivan-petrov",
      "avatar_image_url": "https://example.com/avatar.jpg"
    }
  }
}

Tool

tupik_list_article_categories

Возвращает актуальный список категорий статей. Агент должен вызывать этот метод перед публикацией статьи, если не уверен, какую категорию указать.

{
  "jsonrpc": "2.0",
  "id": "article-categories-1",
  "method": "tools/call",
  "params": {
    "name": "tupik_list_article_categories",
    "arguments": {}
  }
}

Метод не требует user_token и api_key. Это публичный справочник для выбора категории.

Логика для MCP-агента: сначала вызвать tupik_list_article_categories, выбрать наиболее близкую категорию по смыслу, затем вызвать tupik_publish_article с одним из параметров: category_id, category_title или category_slug. Самый надёжный вариант — category_id.

Tool

tupik_publish_article

Создаёт статью или черновик. Если агент публикует материал из Тунца или AI Semantica, это основной метод.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "tupik_publish_article",
    "arguments": {
      "user_token": "tpu_...",
      "title": "Название статьи",
      "lead": "Короткое описание от 40 до 300 символов",
      "content_html": "<p>Текст статьи</p>",
      "category_title": "Маркетинг",
      "cover_image_url": "https://example.com/cover.jpg",
      "status": "publish",
      "slug": "nazvanie-stati"
    }
  }
}

Откуда взять категорию: категории статей управляются в админке Тупика в разделе категорий контента и видны пользователю в форме /articles/add. MCP-агент должен выбирать одну существующую категорию, а не создавать новую строку произвольно.

Tool

tupik_update_article

Редактирует уже созданную статью или черновик текущего автора. Агент должен передать идентификатор статьи и только те поля, которые реально нужно изменить.

{
  "jsonrpc": "2.0",
  "id": "article-update-1",
  "method": "tools/call",
  "params": {
    "name": "tupik_update_article",
    "arguments": {
      "user_token": "tpu_...",
      "article_id": 38,
      "title": "Новое название статьи",
      "content_html": "<p>Обновленный текст статьи</p>",
      "cover_image_url": "https://example.com/new-cover.jpg",
      "status": "publish"
    }
  }
}

Tool

tupik_delete_article

Снимает свою статью с публикации. Это мягкое удаление: материал скрывается, но запись остаётся в базе для истории, редиректов и возможного восстановления администратором.

{
  "jsonrpc": "2.0",
  "id": "article-delete-1",
  "method": "tools/call",
  "params": {
    "name": "tupik_delete_article",
    "arguments": {
      "user_token": "tpu_...",
      "article_slug": "38-diafragma-myshca-o-kotoroi-vspominayut-togda-kogda-nikogda"
    }
  }
}

Tool

tupik_upsert_speaker

Создаёт или обновляет карточку спикера. У одного пользователя может быть только одна карточка: повторный вызов обновит существующую.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "tupik_upsert_speaker",
    "arguments": {
      "user_token": "tpu_...",
      "name": "Иван Петров",
      "short_position": "SEO и GEO-специалист",
      "city": "Москва",
      "can_travel": true,
      "topics": ["SEO", "GEO / продвижение в нейросетях"],
      "formats": ["Конференция", "Вебинар", "Подкаст-запись"],
      "about": "<p>Помогаю компаниям получать видимость в поиске и нейросетях.</p>",
      "conditions": "<p>Выступаю с докладами и мастер-классами.</p>",
      "website": "https://example.com",
      "video_url": "https://example.com/video",
      "request_email": "speaker@example.com",
      "photo_url": "https://example.com/photo.jpg"
    }
  }
}

Tool

tupik_create_event

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

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "tupik_create_event",
    "arguments": {
      "user_token": "tpu_...",
      "title": "Digital-конференция 2026",
      "event_type": "Конференция",
      "event_date": "2026-08-01",
      "event_date_end": "2026-08-02",
      "city": "Москва",
      "format": "Офлайн",
      "topics": ["SEO", "GEO / продвижение в нейросетях"],
      "lead": "Конференция о поиске, нейросетях и продвижении брендов в AI-ответах.",
      "description": "<p>В программе доклады, панели и разборы кейсов.</p>",
      "source_url": "https://example.com/event",
      "needs_speakers": "yes",
      "speaker_terms": "free",
      "deadline": "2026-07-20",
      "cover_image_url": "https://example.com/event-cover.jpg"
    }
  }
}

Tool

tupik_update_event

Редактирует мероприятие текущего пользователя. После изменения карточка снова уходит на модерацию, чтобы в каталог не попадал мусор и подменённые рекламные события.

{
  "jsonrpc": "2.0",
  "id": "event-update-1",
  "method": "tools/call",
  "params": {
    "name": "tupik_update_event",
    "arguments": {
      "user_token": "tpu_...",
      "event_id": 12,
      "title": "Обновлённая конференция",
      "event_date": "2026-08-10",
      "event_date_end": "2026-08-11",
      "needs_speakers": "yes",
      "speaker_terms": "paid",
      "deadline": "2026-07-25"
    }
  }
}

Tool

tupik_delete_event

Скрывает своё мероприятие из каталога. Используйте, если событие отменили, добавили по ошибке или нужно убрать карточку.

{
  "jsonrpc": "2.0",
  "id": "event-delete-1",
  "method": "tools/call",
  "params": {
    "name": "tupik_delete_event",
    "arguments": {
      "user_token": "tpu_...",
      "event_slug": "digital-konferencija-2026"
    }
  }
}

Tool

tupik_subscribe_events

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

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "tupik_subscribe_events",
    "arguments": {
      "user_token": "tpu_...",
      "title": "SEO и GEO онлайн",
      "topics": ["SEO", "GEO / продвижение в нейросетях"],
      "cities": ["Онлайн", "Москва"],
      "formats": ["Онлайн", "Гибрид"],
      "event_types": ["Конференция", "Вебинар"],
      "needs_speakers": "yes",
      "date_from": "2026-06-01",
      "date_to": "2026-12-31"
    }
  }
}

Важно: в подписке должен быть хотя бы один фильтр: тема, город, формат, тип или статус “нужны спикеры”.

Справочники

Откуда брать категории, темы, форматы и id

Ошибки

Типовые ответы с ошибками

План улучшений

Что ещё нужно расписать и добавить

1. Публичные справочники: категории статей уже доступны через tupik_list_article_categories. Следом стоит добавить tupik_list_topics, tupik_list_event_types, tupik_list_formats, чтобы агент не угадывал названия.
2. Проверка slug: добавить метод, который заранее проверяет доступность ЧПУ для пользователя, статьи, спикера или конференции.
3. Редактирование созданных сущностей: сейчас API создаёт статьи и конференции, а для спикера делает upsert. Нужны отдельные методы обновления статей и конференций.
4. Статистика: добавить tools для показов, просмотров, дочитываний, лайков, комментариев и избранного по статьям автора.
5. Файлы: добавить отдельный метод загрузки изображения, который вернёт готовый URL, чтобы агент мог сначала загрузить картинку, а потом использовать её в статье, спикере или мероприятии.
6. OpenAPI: подготовить /api/openapi.json, чтобы программисты могли подключать REST API автоматически.
7. WebMCP widget: при необходимости добавить клиентский слой WebMCP для браузерных агентов. Текущая страница уже раскрывает инструменты и MCP endpoint, но не заменяет локальный WebSocket-мост.

Manifest

Живой список tools

Ниже находится JSON, который отдаёт текущий MCP Server. Его можно использовать для автоматической проверки схем.

{
    "name": "Tupik MCP Server",
    "version": "0.1.0",
    "protocol": "jsonrpc",
    "endpoint": "https:\/\/to-pick.ru\/mcp\/server",
    "tools": [
        {
            "name": "tupik_get_me",
            "description": "Проверить личный API-токен Тупика и получить данные текущего пользователя.",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "user_token": {
                        "type": "string",
                        "description": "Личный токен пользователя tpu_... Можно передать вместо Authorization: Bearer."
                    }
                }
            }
        },
        {
            "name": "tupik_create_user",
            "description": "Создать пользователя Тупика для внешнего сервиса. Требует сервисный X-Tupik-Api-Key.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "email",
                    "name"
                ],
                "properties": {
                    "api_key": {
                        "type": "string",
                        "description": "Сервисный API-ключ интеграции."
                    },
                    "email": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "password": {
                        "type": "string"
                    },
                    "slug": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "name": "tupik_issue_user_token",
            "description": "Получить пользовательский токен для существующего пользователя. Требует сервисный X-Tupik-Api-Key.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "email"
                ],
                "properties": {
                    "api_key": {
                        "type": "string"
                    },
                    "email": {
                        "type": "string"
                    },
                    "ttl_days": {
                        "type": "integer"
                    }
                }
            }
        },
        {
            "name": "tupik_update_profile",
            "description": "Обновить профиль пользователя Тупика: имя, описание, роль, компанию, сайт, ЧПУ.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "user_token"
                ],
                "properties": {
                    "user_token": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "about": {
                        "type": "string"
                    },
                    "role": {
                        "type": "string"
                    },
                    "company": {
                        "type": "string"
                    },
                    "website": {
                        "type": "string"
                    },
                    "slug": {
                        "type": "string"
                    },
                    "avatar_image_url": {
                        "type": "string"
                    },
                    "avatar_image_base64": {
                        "type": "string"
                    },
                    "avatar_url": {
                        "type": "string"
                    },
                    "avatar_base64": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "name": "tupik_list_article_categories",
            "description": "Получить список категорий статей Тупика для публикации: category_id, category_title, category_slug и публичный URL категории.",
            "inputSchema": {
                "type": "object",
                "properties": []
            }
        },
        {
            "name": "tupik_publish_article",
            "description": "Создать статью или черновик в Тупике с HTML-текстом, лидом, категорией и обложкой.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "user_token",
                    "title",
                    "content_html"
                ],
                "properties": {
                    "user_token": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "lead": {
                        "type": "string"
                    },
                    "content_html": {
                        "type": "string"
                    },
                    "category_id": {
                        "type": "integer"
                    },
                    "category_title": {
                        "type": "string"
                    },
                    "category_slug": {
                        "type": "string"
                    },
                    "cover_image_url": {
                        "type": "string"
                    },
                    "cover_image_base64": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "publish",
                            "draft"
                        ]
                    },
                    "slug": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "name": "tupik_update_article",
            "description": "Отредактировать свою статью или черновик в Тупике. Передайте article_id или article_slug и только те поля, которые нужно изменить.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "user_token"
                ],
                "properties": {
                    "user_token": {
                        "type": "string"
                    },
                    "article_id": {
                        "type": "integer"
                    },
                    "article_slug": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "lead": {
                        "type": "string"
                    },
                    "content_html": {
                        "type": "string"
                    },
                    "category_title": {
                        "type": "string"
                    },
                    "category_slug": {
                        "type": "string"
                    },
                    "category_id": {
                        "type": "integer"
                    },
                    "cover_image_url": {
                        "type": "string"
                    },
                    "cover_image_base64": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "publish",
                            "draft"
                        ]
                    },
                    "slug": {
                        "type": "string"
                    },
                    "seo_title": {
                        "type": "string"
                    },
                    "seo_description": {
                        "type": "string"
                    },
                    "seo_keywords": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "name": "tupik_delete_article",
            "description": "Удалить свою статью или черновик из публикации. Передайте article_id или article_slug.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "user_token"
                ],
                "properties": {
                    "user_token": {
                        "type": "string"
                    },
                    "article_id": {
                        "type": "integer"
                    },
                    "article_slug": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "name": "tupik_upsert_speaker",
            "description": "Создать или обновить карточку спикера пользователя.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "user_token",
                    "name"
                ],
                "properties": {
                    "user_token": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "short_position": {
                        "type": "string"
                    },
                    "city": {
                        "type": "string"
                    },
                    "can_travel": {
                        "type": "boolean"
                    },
                    "topics": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "formats": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "about": {
                        "type": "string"
                    },
                    "conditions": {
                        "type": "string"
                    },
                    "website": {
                        "type": "string"
                    },
                    "video_url": {
                        "type": "string"
                    },
                    "photo_url": {
                        "type": "string"
                    },
                    "photo_base64": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "name": "tupik_create_event",
            "description": "Добавить конференцию или мероприятие в Тупик. Мероприятие уходит на модерацию.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "user_token",
                    "title",
                    "event_date",
                    "format",
                    "event_type",
                    "city",
                    "lead",
                    "source_url"
                ],
                "properties": {
                    "user_token": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "event_type": {
                        "type": "string"
                    },
                    "event_date": {
                        "type": "string"
                    },
                    "event_date_end": {
                        "type": "string"
                    },
                    "city": {
                        "type": "string"
                    },
                    "format": {
                        "type": "string"
                    },
                    "topics": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "lead": {
                        "type": "string"
                    },
                    "description": {
                        "type": "string"
                    },
                    "source_url": {
                        "type": "string"
                    },
                    "needs_speakers": {
                        "type": "string"
                    },
                    "speaker_terms": {
                        "type": "string"
                    },
                    "deadline": {
                        "type": "string"
                    },
                    "cover_image_url": {
                        "type": "string"
                    },
                    "cover_image_base64": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "name": "tupik_update_event",
            "description": "Отредактировать своё мероприятие или конференцию. Передайте event_id или event_slug и только те поля, которые нужно изменить.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "user_token"
                ],
                "properties": {
                    "user_token": {
                        "type": "string"
                    },
                    "event_id": {
                        "type": "integer"
                    },
                    "event_slug": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "event_type": {
                        "type": "string"
                    },
                    "event_date": {
                        "type": "string"
                    },
                    "event_date_end": {
                        "type": "string"
                    },
                    "city": {
                        "type": "string"
                    },
                    "format": {
                        "type": "string"
                    },
                    "topics": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "lead": {
                        "type": "string"
                    },
                    "description": {
                        "type": "string"
                    },
                    "conditions": {
                        "type": "string"
                    },
                    "source_url": {
                        "type": "string"
                    },
                    "needs_speakers": {
                        "type": "string"
                    },
                    "speaker_terms": {
                        "type": "string"
                    },
                    "deadline": {
                        "type": "string"
                    },
                    "cover_image_url": {
                        "type": "string"
                    },
                    "cover_image_base64": {
                        "type": "string"
                    },
                    "slug": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "name": "tupik_delete_event",
            "description": "Удалить своё мероприятие или конференцию. Передайте event_id или event_slug.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "user_token"
                ],
                "properties": {
                    "user_token": {
                        "type": "string"
                    },
                    "event_id": {
                        "type": "integer"
                    },
                    "event_slug": {
                        "type": "string"
                    }
                }
            }
        },
        {
            "name": "tupik_subscribe_events",
            "description": "Создать подписку на новые конференции по темам, городам, форматам и типам.",
            "inputSchema": {
                "type": "object",
                "required": [
                    "user_token"
                ],
                "properties": {
                    "user_token": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "topics": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "cities": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "formats": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "event_types": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "needs_speakers": {
                        "type": "string"
                    },
                    "date_from": {
                        "type": "string"
                    },
                    "date_to": {
                        "type": "string"
                    }
                }
            }
        }
    ]
}