API Overview

The Gnosari MCP Server exposes 17 gnosari_* tools organized by domain.

Tool Surface

17 Tools

File	Tool	Purpose
`agent_crud.py`	`gnosari_create`	Create a bare private agent with name and instructions
`agent_crud.py`	`gnosari_get`	Get full agent overview (`GnosariOverview`)
`agent_crud.py`	`gnosari_update`	Update identity and model settings
`agent_crud.py`	`gnosari_delete`	Two-phase delete with confirmation
`agent_config.py`	`gnosari_manage_instructions`	Replace, append, or prepend instructions
`agent_config.py`	`gnosari_manage_access`	Set access level, URI, password
`agent_config.py`	`gnosari_manage_appearance`	Set greeting, theme, prompts, image
`manage_resources.py`	`gnosari_manage_traits`	CRUD + assign/remove personality traits
`manage_resources.py`	`gnosari_manage_knowledge`	CRUD + assign/remove knowledge sources
`manage_resources.py`	`gnosari_manage_data_collection`	CRUD + assign/remove data collection templates
`discovery.py`	`gnosari_search`	Unified search across agents, traits, templates, knowledge
`discovery.py`	`gnosari_check_uri`	Check URI availability before publishing
`link.py`	`gnosari_manage_link`	Consolidated agent-link CRUD (`action: create\|get\|list\|update\|delete\|check_slug`)
`collected_data.py`	`gnosari_collected_data`	Consolidated collected data (`action: list\|stats`)
`collected_data.py`	`gnosari_collected_data_delete`	Two-phase delete of collected records (confirm → execute)
`utility.py`	`gnosari_embed_code`	Generate HTML embed snippet for the chat widget
`utility.py`	`gnosari_health`	Server health check

Atomic Decomposition Pattern

The previous design used a single create_agent call with 20+ parameters. The new design uses atomic decomposition:

gnosari_create(name, instructions)     → bare agent with gnosari_id
  ↓
gnosari_manage_instructions(replace)   → refined instructions
  ↓
gnosari_manage_knowledge(create)       → knowledge source created
gnosari_manage_knowledge(assign)       → knowledge attached
  ↓
gnosari_manage_traits(assign)          → personality traits attached
  ↓
gnosari_manage_appearance(greeting)    → welcome experience configured
  ↓
gnosari_manage_access(PUBLIC, uri)     → agent published at joina.chat/uri

Each step is independent and idempotent in isolation. Configuration tools only modify what you pass — nothing else changes.

Manage Tool Pattern

Five tools use an action-discriminated pattern:

gnosari_manage_traits
gnosari_manage_knowledge
gnosari_manage_data_collection
gnosari_manage_link
gnosari_collected_data

Resource management tools (traits, knowledge, data_collection)

Action	What happens
`create`	Creates a new resource (optionally assigns to agent if `gnosari_id` provided)
`list`	Lists all resources for the account
`get`	Retrieves a single resource by ID
`update`	Updates resource fields
`delete`	Removes the resource permanently
`assign`	Links an existing resource to an agent
`remove`	Unlinks a resource from an agent

Link tool (gnosari_manage_link)

Action	What happens
`create`	Creates a shareable agent link, either `chat` or `conversation` presentation
`get`	Retrieves a single link by ID
`list`	Lists all links for the account
`check_slug`	Checks whether a slug is available (globally unique) before creating
`update`	Updates link fields; supports `clear_fields` to reset greeting/topic/theme/expiry back to inherit
`delete`	Deletes a link permanently

Collected data tool (gnosari_collected_data)

Action	What happens
`list`	Browse collected records with filtering and pagination
`stats`	Dashboard totals; use `group_by_agent=True` for per-agent breakdown

Note: Deleting collected records is a separate tool, gnosari_collected_data_delete — not an action= value on this tool.

Example — create a knowledge source and immediately assign it (type omitted — see the Manage Resources reference for the auto-resolve contract):

python

# One call: create + assign
gnosari_manage_knowledge(
    action="create",
    name="Product Docs",
    url="https://docs.example.com",
    gnosari_id=123  # optional: also assigns to this agent
)

# Or separate: create first, then assign later
gnosari_manage_knowledge(action="create", name="Product Docs", url="https://docs.example.com", type="sitemap")
# returns KnowledgeSourceRead with id=45

gnosari_manage_knowledge(action="assign", source_ids=[45], gnosari_id=123)

Readiness Block

Every gnosari_* tool response (except gnosari_check_uri) includes a readiness block with structured configuration-completeness data. This replaces the old hints: list[str] field.

Fields

Field	Type	Description
`percent`	`int`	Weighted completeness score 0–100. 100 = fully configured
`missing`	`list[str]`	Machine-readable keys for unconfigured areas, e.g. `["knowledge", "traits", "published"]`
`next_steps`	`list[str]`	Up to 3 prioritized actions. Each names the exact tool and what to ask the user

Example — agent just created

python

result = gnosari_create(
    name="Support Bot",
    instructions="...",
    empty_state_title="Ask us anything",
    empty_state_description="We'll get back to you",
    data_collection=DataCollectionInput(...)
)
print(result.readiness)
# Readiness(
#   percent=55,
#   missing=["knowledge", "traits", "published"],
#   next_steps=[
#     "Add knowledge sources with gnosari_manage_knowledge — ask the user for website/sitemap URLs",
#     "Add personality traits with gnosari_manage_traits — ask what tone the agent should use",
#     "Publish the agent with gnosari_manage_access — ask the user for a URI slug"
#   ]
# )

Example — fully configured agent

python

result = gnosari_get(gnosari_id=123)
print(result.readiness)
# Readiness(percent=100, missing=[], next_steps=[])

next_steps are machine-readable: each entry names the exact tool to call and what to ask the user, so a calling agent can drive the configuration workflow deterministically.

Note: gnosari_check_uri keeps a hints field — it returns URI availability and alternative suggestions. That tool does not carry a readiness block.

Return Types

All tools return Pydantic models directly — no {"success": true, "data": ...} envelope. Use attribute access, not dict-key access.

Tool	Return type
`gnosari_create`	`CreatedAgentResult` (`.agent`, `.readiness`, `.published_url`, `.note`)
`gnosari_get`	`GnosariOverview` (full agent snapshot, includes `.readiness`)
`gnosari_update`	`AgentSummaryWithReadiness` (`.agent`, `.readiness`)
`gnosari_delete(confirmed=False)`	`DeleteConfirmationResponse`
`gnosari_delete(confirmed=True)`	`DeletedResponse`
`gnosari_manage_instructions`	`InstructionsResult`
`gnosari_manage_access`	`AgentSummaryWithReadiness` (`.agent`, `.readiness`)
`gnosari_manage_appearance`	`AppearanceResult`
`gnosari_manage_traits`	varies by action (see tool reference)
`gnosari_manage_knowledge`	varies by action (see tool reference)
`gnosari_manage_data_collection`	varies by action (see tool reference)
`gnosari_search`	`SearchResult` or `SearchAllResult`
`gnosari_check_uri`	`UriCheckResult`
`gnosari_manage_link`	varies by action (see Link tools)
`gnosari_collected_data`	`PaginatedExtractedEntitiesResponse`, `StatsRead`, or `StatsByAgentRead` (see collected data tools)
`gnosari_collected_data_delete(confirmed=False)`	`CollectedDataDeleteConfirmation`
`gnosari_collected_data_delete(confirmed=True)`	`CollectedDataDeleteResult`
`gnosari_embed_code`	`EmbedCodeResult`
`gnosari_health`	`dict[str, str]`

On error, exceptions propagate to FastMCP which returns isError: true. The client receives a structured error, not a success: false dict.

Authentication

All tools use header-based authentication resolved by tools/account_resolver.py. Three methods are supported:

Method	Header	Format
API Key	`Gnosari-Api-Key`	`gak_*`
OAuth Bearer	`Authorization`	`Bearer <token>`
User Token	`Gnosari-User-Token`	HS256 JWT

All gnosari_* tools use gnosari_id (not agent_id) as the public parameter name. The resolver maps it to the internal agent_id for core service calls.

Common Sequences

Create and configure a public agent

python

# 1. Create bare agent
result = gnosari_create(name="Support Bot", instructions="You help with product questions...")
gnosari_id = result.agent.gnosari_id

# 2. Add knowledge
gnosari_manage_knowledge(
    action="create",
    name="Product Docs",
    url="https://docs.example.com/sitemap.xml",
    type="sitemap",
    gnosari_id=gnosari_id
)

# 3. Set greeting
gnosari_manage_appearance(
    gnosari_id=gnosari_id,
    greeting="Hi! Ask me anything about our products."
)

# 4. Publish
gnosari_manage_access(
    gnosari_id=gnosari_id,
    access_level="PUBLIC",
    uri="support-bot"
)

# 5. Get overview (hints will be empty when fully configured)
overview = gnosari_get(gnosari_id=gnosari_id)
print(overview.public_url)  # https://joina.chat/acme/support-bot

Check URI before publishing

python

check = gnosari_check_uri(uri="support-bot")
if check.available:
    gnosari_manage_access(gnosari_id=123, access_level="PUBLIC", uri="support-bot")
else:
    print(f"Taken by: {check.current_gnosari_name}")
    print(check.hints)  # ["URI 'support-bot' is taken. Try variations like 'support-bot-2' or 'support-bot-bot'."]

Search for existing agents

python

# Search agents by name
results = gnosari_search(query="support", entity="agents")
for agent in results.results:
    print(agent["name"], agent["id"])

# Search across all entity types
all_results = gnosari_search(query="leads", entity="all")
print(f"Agents: {len(all_results.agents)}, Templates: {len(all_results.templates)}")

View collected data

python

# Stats overview
stats = gnosari_collected_data(action="stats", days=30)
print(f"Total: {stats.total}")

# Drill into records
records = gnosari_collected_data(action="list", template_name="leads", status="new", days=7)
for entry in records.data:
    print(f"{entry.template_name}: {entry.attributes_summary}")

Manage agent links

python

# Create a link for print media
link = gnosari_manage_link(action="create", name="Business Card", slug="card", agent_id=123)
print(link.urls.qr_image)  # printable QR code

# Remap without reprinting
gnosari_manage_link(action="update", link_id=link.id, agent_id=456)

Next Steps

Tools Reference - Complete tool parameter documentation
Listing Tools - Search and discovery tools
Agent Creation Flow - Step-by-step creation workflow

API Overview ​

Tool Surface ​

17 Tools ​

Atomic Decomposition Pattern ​

Manage Tool Pattern ​

Resource management tools (traits, knowledge, data_collection) ​

Link tool (gnosari_manage_link) ​

Collected data tool (gnosari_collected_data) ​

Readiness Block ​

Fields ​

Example — agent just created ​

Example — fully configured agent ​

Return Types ​

Authentication ​

Common Sequences ​

Create and configure a public agent ​

Check URI before publishing ​

Search for existing agents ​

View collected data ​

Manage agent links ​

Next Steps ​

API Overview

Tool Surface

17 Tools

Atomic Decomposition Pattern

Manage Tool Pattern

Resource management tools (traits, knowledge, data_collection)

Link tool (gnosari_manage_link)

Collected data tool (gnosari_collected_data)

Readiness Block

Fields

Example — agent just created

Example — fully configured agent

Return Types

Authentication

Common Sequences

Create and configure a public agent

Check URI before publishing

Search for existing agents

View collected data

Manage agent links

Next Steps