Introduction

Gnosari MCP Server is a Model Context Protocol server that manages AI agents in the Gnosari platform. It enables AI assistants to create, configure, and publish conversational AI agents with automatic data collection capabilities.

What is Gnosari MCP Server?

Gnosari deploys AI agents that anyone can chat with via joina.chat links. Every conversation automatically collects structured data - leads, feedback, bookings, applications - without forms or surveys.

This MCP server provides 19 tools and 9 prompts that let you:

• Create fully-configured agents in a single call
• Configure data collection templates and extraction modes
• Add knowledge sources for domain expertise
• Customize chat themes and personality traits
• Monitor collected data and statistics
• Manage domains for agent publication
• Use guided prompt templates for common workflows (replace forms, migrate from Typeform, generate agent instructions)

Core workflow: Create agent → Set access → Configure data collection → Share joina.chat link → View collected data

Why Gnosari MCP Server?

Problem: Complex Agent Creation

Before v3, creating a Gnosari agent required 127 tools and 12-16 sequential API calls. You had to orchestrate separate calls for:

• Base agent creation
• Knowledge source attachment
• Data collection template setup
• Chat theme configuration
• Domain assignment
• Publishing

This complexity made agent creation slow and error-prone.

Solution: Single-Call Agent Creation

Gnosari MCP Server v3 simplifies agent creation to one call:

create_agent(
    name="Sales Assistant",
    instructions="Help visitors learn about our products...",
    access_level="PUBLIC",
    data_collection={...},
    knowledge_sources=[...],
    chat_theme={...}
)

Everything needed to launch an agent happens in one operation.

Metric	Before v3	Current	Improvement
Tools	127	19	85% reduction
Calls to create agent	12-16	1	92% reduction

Key Features

Agent Lifecycle Management

Create, update, delete, and retrieve agents with comprehensive configuration support.

Automatic Data Collection

Configure templates with custom fields and collection modes (passive, opportunistic, active, guided) to extract structured data from conversations.

Knowledge Integration

Attach knowledge sources (websites, sitemaps) that agents use for domain expertise via RAG.

Access Control

Three access levels: PUBLIC (anyone with link), PASSWORD_PROTECTED (link + password), PRIVATE (API/embed only).

Domain-Based Publishing

Publish agents to joina.chat domains with automatic URL generation.

Chat Customization

Apply themes, personality traits, and custom greetings to match your brand.

Data Monitoring

List collected data with filtering, search, and statistics for dashboard views.

Architecture Overview

Service Layer: The MCP server delegates all business logic to service classes:

• CompleteAgentService: Composite agent creation (orchestrates multiple services)
• AgentService: Core agent CRUD
• KnowledgeService: Knowledge sources
• DataCollectionService: Collected data queries and statistics
• DataTemplateService: Data collection template management
• DomainService: Domain management
• ChatThemeService: Chat theme operations
• TraitService: Personality trait management

Authentication: Three methods supported via MultiAuth composition:

• OAuth 2.1 + PKCE via Authorization: Bearer <JWT> (recommended for Claude Desktop / ChatGPT — automatic)
• Gnosari-Api-Key: gak_... (API key — recommended for automation and Claude Code CLI)
• Gnosari-User-Token: <jwt> (legacy JWT token — for interactive sessions)

Quick Reference

Tools (16)

Tool	Purpose
gnosari_create	Create a live-ready agent in one call (welcome + data collection required; optional greeting, prompts, publish)
gnosari_get	Get full agent overview + readiness block
gnosari_update	Update identity and model settings
gnosari_delete	Permanently remove agent and its data (confirmation flow)
gnosari_manage_instructions	Replace / append / prepend instructions
gnosari_manage_access	Access level, URI, password (domain auto-resolved)
gnosari_manage_appearance	Greeting, welcome screen, prompts, style_preset (curated visual identity), image
gnosari_manage_traits	CRUD + assign/remove personality traits
gnosari_manage_knowledge	CRUD + assign/remove knowledge sources. type is optional — omit it to auto-resolve sitemap vs. discovery from the URL
gnosari_manage_data_collection	CRUD + assign/remove data collection templates
gnosari_search	Unified search (summary rows)
gnosari_check_uri	URI availability (suggests an alternative when taken)
gnosari_manage_link	Shareable agent-link CRUD — chat or immersive conversation presentation (action: create|get|list|update|delete|check_slug)
gnosari_collected_data	Collected data list + stats (action: list|stats)
gnosari_embed_code	HTML embed snippet (gnosari_id: int)
gnosari_health	Check if the server is running

Core Concepts

Before diving into the API, understand these key concepts:

Agents

AI assistants that conduct conversations and collect data. Each agent has:

• Access level: Who can chat with it
• Instructions: What the agent does and how it behaves
• Model: Which LLM to use (GPT-4, Claude, etc.)
• Data collection: What data to extract from conversations
• Knowledge sources: Domain expertise for answering questions
• Chat theme: Appearance and branding
• Public URL: Where to share the agent (joina.chat/...)

See Agent Lifecycle for details.

Data Collection

Automatic extraction of structured data from conversations. Configure:

• Templates: Define fields to collect (name, email, company, etc.)
• Collection modes: How aggressive the extraction should be
• Field types: text, email, number, date, boolean
• AI hints: Guide the extraction engine

See Data Collection for details.

Knowledge System

URL-based content that agents reference during conversations. Features:

• Knowledge sources: Individual URLs (website, sitemap, or crawl-based discovery). Omit type when creating one to auto-resolve the best option from the URL
• Loading states: unloaded → loading → loaded/failed
• RAG integration: Automatic semantic search during conversations

See Knowledge System for details.

What's Next?

• Quick Start - Get running in 5 minutes
• Concepts - Understand agents, data collection, and knowledge
• API Reference - Detailed tool documentation
• Guides - Common workflows and best practices