> ## 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.

# MCP Tools

> Complete reference for all 12 Orchata MCP tools

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:**

<ParamField body="page" type="number">
  Page number (default: 1)
</ParamField>

<ParamField body="pageSize" type="number">
  Items per page (default: 10)
</ParamField>

<ParamField body="status" type="string">
  Filter by status: `active`, `archived`, or `all`
</ParamField>

<ParamField body="metadata" type="object">
  Filter by metadata key-value pairs. Only returns spaces whose metadata contains all specified keys and values.
</ParamField>

**Example:**

```
list_spaces with status="active"
list_spaces with metadata={"team": "engineering"}
```

***

### create\_space

Create a new knowledge space.

**Parameters:**

<ParamField body="name" type="string" required>
  Name of the space
</ParamField>

<ParamField body="description" type="string">
  Description of what the space contains (used by Smart Query)
</ParamField>

<ParamField body="icon" type="string">
  Emoji icon for the space
</ParamField>

<ParamField body="slug" type="string">
  URL-friendly identifier (auto-generated if not provided)
</ParamField>

<ParamField body="metadata" type="object">
  Custom key-value metadata for categorization and filtering
</ParamField>

**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:**

<ParamField body="id" type="string" required>
  Space ID
</ParamField>

**Example:**

```
get_space with id="spc_abc123"
```

***

### update\_space

Update a space's properties.

**Parameters:**

<ParamField body="id" type="string" required>
  Space ID
</ParamField>

<ParamField body="name" type="string">
  New name
</ParamField>

<ParamField body="description" type="string">
  New description
</ParamField>

<ParamField body="icon" type="string">
  New icon
</ParamField>

<ParamField body="slug" type="string">
  New slug
</ParamField>

<ParamField body="metadata" type="object">
  Updated metadata key-value pairs (replaces existing metadata)
</ParamField>

<ParamField body="isArchived" type="boolean">
  Archive status
</ParamField>

**Example:**

```
update_space with id="spc_abc123" description="Updated documentation" metadata={"team": "product"}
```

***

### delete\_space

Archive a space (soft delete).

**Parameters:**

<ParamField body="id" type="string" required>
  Space ID
</ParamField>

**Example:**

```
delete_space with id="spc_abc123"
```

<Warning>
  Deleting a space archives it. Documents within the space are preserved but no longer searchable.
</Warning>

***

## Document Management

### list\_documents

List documents in a space.

**Parameters:**

<ParamField body="spaceId" type="string" required>
  Space ID
</ParamField>

<ParamField body="page" type="number">
  Page number
</ParamField>

<ParamField body="pageSize" type="number">
  Items per page
</ParamField>

<ParamField body="status" type="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.
</ParamField>

<ParamField body="metadata" type="object">
  Filter by document metadata key-value pairs. Only returns documents whose metadata contains all specified keys and values.
</ParamField>

**Example:**

```
list_documents with spaceId="spc_abc123" status="COMPLETED"
list_documents with spaceId="spc_abc123" metadata={"author": "engineering"}
```

<Note>
  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.
</Note>

***

### upload\_document

Upload text or markdown content as a document.

**Parameters:**

<ParamField body="spaceId" type="string" required>
  Space ID to upload to
</ParamField>

<ParamField body="content" type="string" required>
  Markdown or text content
</ParamField>

<ParamField body="filename" type="string">
  Filename (default: `document.md`)
</ParamField>

<ParamField body="metadata" type="object">
  Optional key-value metadata
</ParamField>

**Example:**

```
upload_document with spaceId="spc_abc123" content="# Getting Started\n\nWelcome..." filename="getting-started.md"
```

<Note>
  Documents are processed asynchronously. Check the status using `get_document` before querying.
</Note>

***

### get\_document

Get details of a specific document.

**Parameters:**

<ParamField body="id" type="string" required>
  Document ID
</ParamField>

<ParamField body="spaceId" type="string" required>
  Space ID
</ParamField>

**Example:**

```
get_document with id="doc_xyz789" spaceId="spc_abc123"
```

***

### update\_document

Update document metadata.

**Parameters:**

<ParamField body="id" type="string" required>
  Document ID
</ParamField>

<ParamField body="spaceId" type="string" required>
  Space ID
</ParamField>

<ParamField body="metadata" type="object">
  New metadata key-value pairs
</ParamField>

**Example:**

```
update_document with id="doc_xyz789" spaceId="spc_abc123" metadata={"version": "2.0"}
```

***

### delete\_document

Permanently delete a document.

**Parameters:**

<ParamField body="id" type="string" required>
  Document ID
</ParamField>

<ParamField body="spaceId" type="string" required>
  Space ID
</ParamField>

**Example:**

```
delete_document with id="doc_xyz789" spaceId="spc_abc123"
```

<Warning>
  Document deletion is permanent. The document and all its chunks are removed.
</Warning>

***

## Querying

### query\_spaces

Search for semantically similar content across spaces.

**Parameters:**

<ParamField body="query" type="string" required>
  Natural language search query
</ParamField>

<ParamField body="spaceIds" type="string | string[]">
  One or more space IDs to search, or '\*' for all spaces
</ParamField>

<ParamField body="topK" type="number">
  Maximum results (default: 5)
</ParamField>

<ParamField body="threshold" type="number">
  Similarity threshold 0-1 (default: 0.5, higher = more relevant)
</ParamField>

<ParamField body="metadata" type="object">
  Filter results by document metadata. Only returns results from documents whose metadata contains all specified keys and values.
</ParamField>

<ParamField body="expandContext" type="boolean">
  Include adjacent chunks for context (default: false)
</ParamField>

<ParamField body="compact" type="boolean">
  Use compact response format (default: true)
</ParamField>

**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"}
```

<Tip>
  Use `threshold` to filter out low-relevance results. A value of 0.7 works well for most use cases.
</Tip>

***

### smart\_query

Discover which spaces are most relevant for your query.

**Parameters:**

<ParamField body="query" type="string" required>
  Natural language query
</ParamField>

<ParamField body="maxSpaces" type="number">
  Maximum recommendations (default: 5)
</ParamField>

<ParamField body="relevanceMethod" type="string">
  Relevance method: `keyword`, `embedding`, or `hybrid` (default: `hybrid`)
</ParamField>

<ParamField body="keywordWeight" type="number">
  Weight for keyword matching in hybrid mode, 0-1 (default: 0.5)
</ParamField>

**Example:**

```
smart_query with query="How do I install the SDK?" maxSpaces=3
```

<Tip>
  Use `smart_query` when you don't know which space contains the information. It analyzes space descriptions to recommend the best matches.
</Tip>

***

## 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

<CardGroup cols={2}>
  <Card title="Resources & Prompts" icon="book-open" href="/mcp/resources">
    Learn about MCP resources and prompts.
  </Card>

  <Card title="Setup Guides" icon="gear" href="/mcp/setup/cursor">
    Configure your AI tool for Orchata MCP.
  </Card>
</CardGroup>