Skip to main content
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:
​
number
Page number (default: 1)
​
number
Items per page (default: 10)
​
string
Filter by status: active, archived, or all
​
object
Filter by metadata key-value pairs. Only returns spaces whose metadata contains all specified keys and values.
Example:

​
create_space

Create a new knowledge space. Parameters:
​
string
required
Name of the space
​
string
Description of what the space contains (used by Smart Query)
​
string
Emoji icon for the space
​
string
URL-friendly identifier (auto-generated if not provided)
​
object
Custom key-value metadata for categorization and filtering
Example:

​
get_space

Get details of a specific space. Parameters:
​
string
required
Space ID
Example:

​
update_space

Update a space’s properties. Parameters:
​
string
required
Space ID
​
string
New name
​
string
New description
​
string
New icon
​
string
New slug
​
object
Updated metadata key-value pairs (replaces existing metadata)
​
boolean
Archive status
Example:

​
delete_space

Archive a space (soft delete). Parameters:
​
string
required
Space ID
Example:
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:
​
string
required
Space ID
​
number
Page number
​
number
Items per page
​
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.
​
object
Filter by document metadata key-value pairs. Only returns documents whose metadata contains all specified keys and values.
Example:
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:
​
string
required
Space ID to upload to
​
string
required
Markdown or text content
​
string
Filename (default: document.md)
​
object
Optional key-value metadata
Example:
Documents are processed asynchronously. Check the status using get_document before querying.

​
get_document

Get details of a specific document. Parameters:
​
string
required
Document ID
​
string
required
Space ID
Example:

​
update_document

Update document metadata. Parameters:
​
string
required
Document ID
​
string
required
Space ID
​
object
New metadata key-value pairs
Example:

​
delete_document

Permanently delete a document. Parameters:
​
string
required
Document ID
​
string
required
Space ID
Example:
Document deletion is permanent. The document and all its chunks are removed.

​
Querying

​
query_spaces

Search for semantically similar content across spaces. Parameters:
​
string
required
Natural language search query
​
string | string[]
One or more space IDs to search, or ’*’ for all spaces
​
number
Maximum results (default: 5)
​
number
Similarity threshold 0-1 (default: 0.5, higher = more relevant)
​
object
Filter results by document metadata. Only returns results from documents whose metadata contains all specified keys and values.
​
boolean
Include adjacent chunks for context (default: false)
​
boolean
Use compact response format (default: true)
Example:
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:
​
string
required
Natural language query
​
number
Maximum recommendations (default: 5)
​
string
Relevance method: keyword, embedding, or hybrid (default: hybrid)
​
number
Weight for keyword matching in hybrid mode, 0-1 (default: 0.5)
Example:
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.