Skip to main content

Documentation Index

Fetch the complete documentation index at: https://orchata.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Orchata MCP server exposes 12 tools for managing spaces, documents, and queries. AI assistants can use these tools to interact with your knowledge base.

​
Space Management

​
list_spaces

List all knowledge spaces in your organization. Parameters:
​
page
number
Page number (default: 1)
​
pageSize
number
Items per page (default: 10)
​
status
string
Filter by status: active, archived, or all
​
metadata
object
Filter by metadata key-value pairs. Only returns spaces whose metadata contains all specified keys and values.
Example: 
list_spaces with status="active"
list_spaces with metadata={"team": "engineering"}

​
create_space

Create a new knowledge space. Parameters:
​
name
string
required
Name of the space
​
description
string
Description of what the space contains (used by Smart Query)
​
icon
string
Emoji icon for the space
​
slug
string
URL-friendly identifier (auto-generated if not provided)
​
metadata
object
Custom key-value metadata for categorization and filtering
Example: 
create_space with name="Product Documentation" description="Technical docs and API reference" metadata={"team": "engineering"}

​
get_space

Get details of a specific space. Parameters:
​
id
string
required
Space ID
Example: 
get_space with id="spc_abc123"

​
update_space

Update a space’s properties. Parameters:
​
id
string
required
Space ID
​
name
string
New name
​
description
string
New description
​
icon
string
New icon
​
slug
string
New slug
​
metadata
object
Updated metadata key-value pairs (replaces existing metadata)
​
isArchived
boolean
Archive status
Example: 
update_space with id="spc_abc123" description="Updated documentation" metadata={"team": "product"}

​
delete_space

Archive a space (soft delete). Parameters:
​
id
string
required
Space ID
Example: 
delete_space with id="spc_abc123"
Deleting a space archives it. Documents within the space are preserved but no longer searchable.

​
Document Management

​
list_documents

List documents in a space. Parameters:
​
spaceId
string
required
Space ID
​
page
number
Page number
​
pageSize
number
Items per page
​
status
string
Filter by document processing status. Valid values (case-insensitive): PENDING, PROCESSING, COMPLETED, FAILED. Input is normalized to uppercase automatically. Note: These are document processing statuses, not space statuses.
​
metadata
object
Filter by document metadata key-value pairs. Only returns documents whose metadata contains all specified keys and values.
Example: 
list_documents with spaceId="spc_abc123" status="COMPLETED"
list_documents with spaceId="spc_abc123" metadata={"author": "engineering"}
The status parameter filters by document processing status. Valid values are: PENDING (not yet processed), PROCESSING (currently being processed), COMPLETED (ready for querying), or FAILED (processing error). Case-insensitive input is accepted (e.g., “completed”, “COMPLETED”, or “Completed” all work). Do not use space statuses like “active” here.

​
upload_document

Upload text or markdown content as a document. Parameters:
​
spaceId
string
required
Space ID to upload to
​
content
string
required
Markdown or text content
​
filename
string
Filename (default: document.md)
​
metadata
object
Optional key-value metadata
Example: 
upload_document with spaceId="spc_abc123" content="# Getting Started\n\nWelcome..." filename="getting-started.md"
Documents are processed asynchronously. Check the status using get_document before querying.

​
get_document

Get details of a specific document. Parameters:
​
id
string
required
Document ID
​
spaceId
string
required
Space ID
Example: 
get_document with id="doc_xyz789" spaceId="spc_abc123"

​
update_document

Update document metadata. Parameters:
​
id
string
required
Document ID
​
spaceId
string
required
Space ID
​
metadata
object
New metadata key-value pairs
Example: 
update_document with id="doc_xyz789" spaceId="spc_abc123" metadata={"version": "2.0"}

​
delete_document

Permanently delete a document. Parameters:
​
id
string
required
Document ID
​
spaceId
string
required
Space ID
Example: 
delete_document with id="doc_xyz789" spaceId="spc_abc123"
Document deletion is permanent. The document and all its chunks are removed.

​
Querying

​
query_spaces

Search for semantically similar content across spaces. Parameters:
​
query
string
required
Natural language search query
​
spaceIds
string | string[]
One or more space IDs to search, or ’*’ for all spaces
​
topK
number
Maximum results (default: 5)
​
threshold
number
Similarity threshold 0-1 (default: 0.5, higher = more relevant)
​
metadata
object
Filter results by document metadata. Only returns results from documents whose metadata contains all specified keys and values.
​
expandContext
boolean
Include adjacent chunks for context (default: false)
​
compact
boolean
Use compact response format (default: true)
Example: 
query_spaces with query="How do I authenticate API requests?" spaceIds="spc_abc123" topK=5
query_spaces with query="deployment guide" spaceIds="*" metadata={"category": "ops"}
Use threshold to filter out low-relevance results. A value of 0.7 works well for most use cases.

​
smart_query

Discover which spaces are most relevant for your query. Parameters:
​
query
string
required
Natural language query
​
maxSpaces
number
Maximum recommendations (default: 5)
​
relevanceMethod
string
Relevance method: keyword, embedding, or hybrid (default: hybrid)
​
keywordWeight
number
Weight for keyword matching in hybrid mode, 0-1 (default: 0.5)
Example: 
smart_query with query="How do I install the SDK?" maxSpaces=3
Use smart_query when you don’t know which space contains the information. It analyzes space descriptions to recommend the best matches.

​
Tool Usage Patterns

​
Searching for Information

  1. Use smart_query to find relevant spaces
  2. Use query_spaces with the recommended space IDs
  3. Process the results in your response

​
Adding Knowledge

  1. Use list_spaces or create_space to get/create a space
  2. Use upload_document to add content
  3. Use get_document to verify processing completed

​
Managing Content

  1. Use list_documents to see existing content
  2. Use update_document to modify metadata
  3. Use delete_document to remove outdated content

​
Next Steps

Resources & Prompts

Learn about MCP resources and prompts.

Setup Guides

Configure your AI tool for Orchata MCP.