Gnosari MCP

Create AI chatbots that collect structured data from conversations, publish them as joina.chat links, embeds or QR codes, and read the typed records they…

CommunityOnlineNo sign-inGlobalFreeCan modify data

What it can do

  • Gnosari Create: Create a fully-configured, data-collecting AI agent in one call. Welcome screen (empty_state_title + empty_state_description) and a data_collection template are REQUIRED — this produce
  • Gnosari Get: Get a complete overview of an agent's configuration. Returns identity, instructions preview, access settings, appearance, knowledge, traits, data collection, and a structured readiness bl
  • Gnosari Update: Update an agent's identity and model settings. Only modifies provided fields. For instructions, access, appearance, knowledge, traits, and data collection, use dedicated tools. At leas

What data it sees

Do you need an account

No: the server works without sign-in

Create AI chatbots that collect structured data from conversations, publish them as joina.chat links, embeds or QR codes, and read the typed records they capture, all from your AI assistant.

Most chatbots just chat. This one collects data.

The Gnosari MCP server lets Claude, ChatGPT, Cursor or any MCP client create and run your Gnosari chatbots through natural conversation. Create Gnosaris, define what data to collect, share conversation links, and review the structured data your conversations capture, without leaving your AI chat. Everything you do here shows up instantly in the Gnosari dashboard, because both write to the same account.

How to connect

How to connect Gnosari MCP to Claude

The server address to paste into Claude settings:

https://gnosari-mcp--gnosari.run.tools

  1. Open Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector.
  4. Paste the server address copied below into Remote MCP server URL and click Add.
  5. In a chat, click + → Connectors and switch the new connector on.

Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

Authorization

After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

How to connect Gnosari MCP to ChatGPT

The server address to paste into ChatGPT settings:

https://gnosari-mcp--gnosari.run.tools

  1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
  2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
  3. Open Settings → Connectors and click Create.
  4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
  5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
  6. In a new chat open + → Apps/Connectors and enable the connector.

OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

Authorization

On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

How to connect Gnosari MCP to Cursor

The server address to paste into Cursor settings:

https://gnosari-mcp--gnosari.run.tools

Fastest: click Open in Cursor below and confirm the prompt.

Manually:

  1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
  2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
  3. Save the file. The server appears in the MCP list; authorize it there if asked.

Authorization

If the service needs sign-in, an authorize button appears next to the server in the MCP list.

Server tool list (19)

Raw names from tools/list. Only developers need these.

gnosari_createCreate a fully-configured, data-collecting AI agent in one call. Welcome screen (empty_state_title + empty_state_description) and a data_collection template are REQUIRED — this produces a live-ready intake agent, not a bare shell. Optionally set a greeting, suggested prompts, and publish=True to go live immediately. ALL inputs are validated before any write; on failure every error is reported at once and nothing is created. The agent, welcome config, data-collection template + assignment, and optional publish all commit atomically. Raises: ValueError: If any input is invalid (all errors reported at once), or if publish=True and the URI is already taken (the message suggests an available alternative).
gnosari_getGet a complete overview of an agent's configuration. Returns identity, instructions preview, access settings, appearance, knowledge, traits, data collection, and a structured readiness block (percent + missing keys + next steps). Set include_instructions=True for the full instructions text.
gnosari_updateUpdate an agent's identity and model settings. Only modifies provided fields. For instructions, access, appearance, knowledge, traits, and data collection, use dedicated tools. At least one field must be provided. Interactive buttons: set ``interactive_buttons_enabled`` to turn the feature on/off, and ``interactive_buttons_behavior`` to customize WHEN the agent shows buttons. To drop a custom behavior and fall back to the canonical default, pass ``clear_fields=["interactive_buttons_behavior"]`` (never send an empty string). Supplying that field in ``clear_fields`` AND as ``interactive_buttons_behavior`` at the same time is rejected. Instructions are managed by ``gnosari_manage_instructions``. Clearing them is the single exception that lives here: pass ``clear_fields=["instructions"]`` to empty the agent's system prompt. Raises: ValueError: If no update fields are provided, or if a field appears in both ``clear_fields`` and as a value param.
gnosari_deleteDelete an agent and all its associated data. When confirmed=False (default), returns agent details and a warning. When confirmed=True, permanently deletes the agent, its public link, collected data, and all configuration. This cannot be undone.
gnosari_manage_instructionsUpdate an agent's system instructions. Prefer ``action="edit"`` with anchored ``edits`` for any change to existing text: only the changed span is sent, everything else stays byte-identical, and the response's ``applied[].excerpt`` shows what landed so no second read is needed. Use ``replace`` only to write a whole new instruction set, ``append``/``prepend`` to add at either end. The usual flow is ``gnosari_create`` → ``gnosari_get`` (read ``instructions_version``) → this tool with ``expected_version`` set; every response returns the new ``instructions_version`` for the next call. The agent's behavior is defined entirely by its instructions, so craft them carefully. Raises: ValueError: VALIDATION_ERROR for a malformed call, ANCHOR_NOT_FOUND or ANCHOR_AMBIGUOUS for an unusable anchor, CONFLICT for a stale ``expected_version``, or a wizard-guardrail rejection.
gnosari_manage_accessConfigure an agent's access level and public URL. Controls who can access the agent and how. PUBLIC makes the agent available at joina.chat/{uri}. PASSWORD_PROTECTED adds a password gate. PRIVATE restricts to API/embed access only. The publishing domain (joina.chat) is resolved automatically. Raises: ValueError: If PASSWORD_PROTECTED without password, or password with non-PASSWORD_PROTECTED access level.
gnosari_manage_appearanceConfigure an agent's visual appearance and welcome experience. Two kinds of setting reach the chat: * CONTENT (per-agent) — greeting, empty-state title/description, and suggested prompts. Set via greeting / empty_state_* / suggested_prompts. greeting is an overlay: when set, the welcome screen (empty state + prompts) is configured but hidden. * VISUAL identity — pick ONE curated ``style_preset`` (color preset + background pattern). The preset is written to the agent's chat theme, REUSING the agent's existing theme row in place so repeated calls never create duplicate themes. See the ``style_preset`` schema for the full list and which agent purpose each fits. Only provided fields are changed; at least one is required. Raises: ValueError: If no appearance fields are provided. ChatThemeConfigurationError: If the resolved theme blob is invalid — the message names the exact offending key to fix.
gnosari_manage_traitsCreate, list, get, update, delete, assign, or remove personality traits. Traits shape how an agent communicates. Use assign/remove to link traits to an agent. To change a trait's behavioral instructions, prefer ``action="update"`` with anchored ``instructions_edits``: only the changed span is sent, everything else stays byte-identical, and the response's ``applied[].excerpt`` shows what landed so no second read is needed. Pass whole ``instructions`` only to write a completely new set. The usual flow is ``action="get"`` (read ``instructions_version``) → ``action="update"`` with ``expected_version`` set; every read and write returns the ``instructions_version`` for the next call. Raises: ValueError: VALIDATION_ERROR for a malformed call, ANCHOR_NOT_FOUND or ANCHOR_AMBIGUOUS for an unusable anchor, or CONFLICT for a stale ``expected_version``.
gnosari_manage_knowledgeCreate, list, get, update, delete, assign, or remove knowledge sources. Knowledge sources are documents or websites that give agents expertise.
gnosari_manage_data_collectionCreate, list, get, update, delete, assign, or remove data collection templates. Templates define what structured data agents extract from conversations. Also controls whether visitors can upload files (photos/PDFs) for the agent to read — pass enable_attachments (requires gnosari_id). Assigning a template (action='assign', or create with gnosari_id) turns data collection ON for that agent. Removing a template never turns it off — the enable state is the owner's setting, changed only through the agent's own configuration. Identity: pass ``identity_field`` (create/update) to name the field that holds the person's display name. On update, omitted fields are preserved (preserve-on-omit); to drop the designation pass ``clear_fields=["identity_field"]`` — never an empty string. Listing a field in ``clear_fields`` AND passing it as a value is rejected.
gnosari_searchSearch across Gnosari entities with optional text query and filters. When entity='all', searches agents, traits, templates, and knowledge sources in parallel and groups results by type. When a specific entity is selected, returns only that type. Uses OpenSearch hybrid search when available, with transparent SQL fallback. The ``search_mode`` field in the response indicates which backend produced the results. The access_level filter applies only to agents and is silently ignored for other entity types.
gnosari_check_uriCheck whether a URI is available for publishing an agent. Verifies that the given URI slug is not already taken on the account's default domain (joina.chat). When the URI is taken, the response suggests a concrete available alternative so the agent can publish without guessing.
gnosari_manage_linkCreate and manage shareable links for an agent. Each link gets a unique URL (joina.chat/l/{slug}) and a downloadable QR code, and renders the agent either as a classic chat or as an immersive conversation page. Multiple links can point to the same agent with different greetings, topics, themes, and expiry -- one link per channel (poster, email campaign, personal invitation) so each is tracked separately. Returns the link with ready-to-use URLs -- ``urls.public`` (share this), ``urls.embed`` (iframe src), ``urls.qr_image`` (printable QR).
gnosari_collected_dataList, fetch, or summarise data your agents have collected from conversations. action='list': Browse collected records (leads, feedback, candidates, orders). Filter by agent, template, date range, status, or search text. action='get': Fetch ONE record's full detail by entity_id, including the per-attribute provenance (which conversation message + verbatim quote each value came from) and a session_excerpt of the surrounding conversation messages. Use this after 'list' to drill into a record. action='stats': Dashboard totals -- counts by template, status breakdown, trends. Use group_by_agent=True for per-agent breakdown. Tip: call with action='stats' first to see the big picture, then action='list' to find records, then action='get' for a single record's evidence. Tip: for a full, filter-aware CSV download of collected data (all matching records, not a single page), use the REST endpoint GET /api/v1/entities/export instead of paging this list action. Args: action: 'list' to browse records, 'get' for one record's detail, 'stats' for dashboard totals. agent_id: Filter by a specific agent. entity_id: Id of the record to fetch (required for action='get'). template_name: Filter by template name (list only). days: Relative date filter in days. Omit for all-time (no cutoff). status: Filter by data status (list only). search: Search within collected data attributes, agent name, or data type name (list only). skip: Pagination offset (list only). limit: Pagination limit (list only). include_facets: Include filter-aware per-type and per-status facet counts on the response (list only). group_by_agent: Per-agent stats breakdown (stats only).
gnosari_collected_data_deletePermanently delete collected data records (leads, feedback, etc.). When confirmed=False (default), returns a confirmation summary — the count of records that would be removed plus an irreversibility warning. NO deletion happens. When confirmed=True, permanently deletes the records. Account-scoped: ids that do not belong to your account are silently skipped, so ``deleted`` reflects only your own rows. This cannot be undone. Args: entity_ids: Ids of the records to delete. confirmed: Must be True to actually delete.
gnosari_extraction_statusWhether any conversation capture is still being extracted. Answers "has the data landed yet?" without guessing from an empty list: a conversation's structured records appear a couple of minutes after the conversation ends, so an empty collected-data list means "still processing" while this reports processing=True, and "genuinely nothing was captured" once it reports processing=False. Args: agent_id: Optional narrowing to one agent.
gnosari_manage_webhooksManage outbound webhook destinations for the account. Actions: list, get, create, update, activate, deactivate, delete, deliveries (the paginated, newest-first attempt history with outcome and failure reason per attempt -- use it to diagnose failures). Event kinds are returned with a display name and one-line description each, so they can be reported to the user without interpreting raw topic ids. The signing secret is NEVER returned by this tool and cannot be read through it -- view and copy it in the dashboard destination view at /settings/webhooks/{id}.
gnosari_embed_codeGenerate an HTML embed snippet for the Gnosari chat widget. Returns a ready-to-paste HTML snippet that adds the chat widget to any website. The snippet carries the Gnosari's public URI -- the only value the widget loader resolves an agent by -- so the Gnosari must have a public URI before it can be embedded. Only settings that differ from the loader's own defaults are printed, which keeps the snippet to the smallest thing that renders a working widget. Paste it right before the closing ``</body>`` tag of every page that should show the chat. Raises: AgentNotFoundError: The Gnosari does not exist, or belongs to another account. AgentValidationError: The Gnosari has no public URI yet.
gnosari_healthHealth check for monitoring Gnosari Manager MCP server status. Returns server health status, name, version, and configured API URL.