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:
​
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.