Gnosari Documentation

Appearance

Quick Start ​

Get your first AI agent running in 5 minutes with Gnosari MCP Server.

Prerequisites ​

Before starting, ensure you have:

  • MCP Client: Claude Desktop, Cline, or any MCP-compatible client
  • Python 3.9+: For running the server directly (or use Docker)
  • Gnosari API Access: API URL and authentication credentials

Environment Variables:

  • GNOSARI_API_URL: Your Gnosari API endpoint (e.g., http://localhost:8000 or https://api.gnosari.com)
  • GNOSARI_API_KEY or GNOSARI_USER_TOKEN: Authentication credentials

Installation ​

Add to your claude_desktop_config.json:

json
{
  "mcpServers": {
    "gnosari-manager": {
      "command": "uvx",
      "args": ["gnosari-mcp-server"],
      "env": {
        "GNOSARI_API_URL": "http://localhost:8000",
        "GNOSARI_API_KEY": "gak_your_api_key_here"
      }
    }
  }
}

Location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop.

Via Docker ​

bash
docker run -d \
  --name gnosari-mcp \
  -e GNOSARI_API_URL=http://localhost:8000 \
  -e GNOSARI_API_KEY=gak_your_key \
  -p 8080:8080 \
  gnosari/mcp-server:latest

Via Python ​

bash
# Clone repository
git clone https://github.com/neomanex/gnosari-mcp.git
cd gnosari/mcp

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export GNOSARI_API_URL=http://localhost:8000
export GNOSARI_API_KEY=gak_your_key

# Run server
python server.py

Verify Installation ​

Test the server with a health check:

Using Claude Desktop:

Ask Claude: "Check Gnosari MCP health"

Using Python:

python
from mcp import Client

client = Client("gnosari-manager")
result = client.call_tool("gnosari_health_check")
print(result)
# Output: {"status": "healthy", "server": "gnosari-mcp", "version": "0.3.0"}

Your First Agent ​

Let's create a simple customer support agent.

Step 1: Discover Available Configuration ​

First, check what domains and templates are available.

python
# List data collection templates
templates = gnosari_manage_data_collection(action="list")
# Returns: Available data collection templates

# (Publishing domain is resolved server-side — no domain listing tool.)

Step 2: Create the Agent ​

gnosari_create is a composite, validate-first, atomic call. A welcome screen and a data-collection template are required — every created agent is live-ready.

Private agent:

python
result = gnosari_create(
    name="Support Bot",
    instructions="You are a helpful customer support agent. Be friendly and professional.",
    empty_state_title="How can we help?",
    empty_state_description="Ask us anything and we'll point you the right way.",
    data_collection={
        "name": "Support Intake",
        "description": "Captures the visitor's issue and contact",
        "mode": "active",
        "fields": [
            {"name": "email", "field_type": "email",
             "description": "Contact email", "required": True},
        ],
    },
)

print(result.agent.id)            # 123
print(result.agent.name)          # "Support Bot"
print(result.readiness.percent)   # weighted completeness
print(result.readiness.next_steps)  # what to configure next

Publish live in the same call:

python
result = gnosari_create(
    name="Product Assistant",
    instructions="Help users understand our products.",
    empty_state_title="Ask about our products",
    empty_state_description="What would you like to know?",
    data_collection={
        "name": "Leads", "description": "Lead capture", "mode": "active",
        "fields": [{"name": "email", "field_type": "email",
                    "description": "Email", "required": True}],
    },
    publish=True,
    uri="product-help",
)
print(result.published_url)  # https://joina.chat/product-help

Step 3: Verify the Agent ​

python
# Full agent overview + readiness block
agent = gnosari_get(gnosari_id=123)

print(f"Agent: {agent.name}")
print(f"Status: {agent.access_level}")
if agent.public_url:
    print(f"URL: {agent.public_url}")
print(f"Readiness: {agent.readiness.percent}% — missing {agent.readiness.missing}")

Step 4: Share or Embed ​

For public agents:

Visit the public URL:

https://joina.chat/product-help

Or embed with widget:

html
<script src="https://cdn.gnosari.com/widget.js"></script>
<script>
  GnosariWidget.init({
    agentUri: "product-help",
    position: "bottom-right"
  });
</script>

Common Patterns ​

Pattern 1: Simple Chatbot ​

python
create_agent(
    name="FAQ Bot",
    instructions="Answer common questions about our service."
)

Pattern 2: Knowledge-Based Assistant ​

python
create_agent(
    name="Docs Assistant",
    instructions="Help users navigate documentation.",
    knowledge_sources=[
        {"name": "Docs", "url": "https://docs.example.com"}
        # "type" omitted — the server auto-resolves sitemap vs. discovery
    ]
)

Pattern 3: Lead Collection Agent ​

python
create_agent(
    name="Sales Bot",
    instructions="Engage visitors and collect contact information.",
    access_level="PUBLIC",
    data_collection={
        "template_name": "Lead Capture",
        "fields": [
            {
                "name": "email",
                "type": "email",
                "required": True,
                "ai_hint": "Contact email address"
            }
        ],
        "collection_mode": "active"
    }
)

Next Steps ​

Learn More:

Advanced Topics:

Troubleshooting:

  • Can't connect? Check GNOSARI_API_URL is correct
  • Authentication failed? Verify GNOSARI_API_KEY or GNOSARI_USER_TOKEN
  • Knowledge not loading? Check URL is public and accessible

Quick Reference ​

ActionTool
Health checkgnosari_health()
Create agentgnosari_create(name=..., instructions=..., empty_state_title=..., empty_state_description=..., data_collection=...)
Get agentgnosari_get(gnosari_id=123)
Update agentgnosari_update(gnosari_id=123, model="gpt-5-mini")
Delete agentgnosari_delete(gnosari_id=123, confirmed=True)
Search / listgnosari_search(entity="agents", query="...")
List traitsgnosari_manage_traits(action="list")
List templatesgnosari_manage_data_collection(action="list")
List knowledge sourcesgnosari_manage_knowledge(action="list")