Skip to content

mcp-tools.md

Latest commit

 

History

History
467 lines (314 loc) · 12.2 KB

mcp-tools.md

File metadata and controls

467 lines (314 loc) · 12.2 KB

MCP Tools Reference

Connapse exposes 11 tools via the Model Context Protocol server at /mcp. All tools require authentication — see Using with Claude (MCP) for setup.

Quick Reference

Tool Description Access
container_create Create a new container for organizing documents Write
container_list List all containers with document counts Read
container_delete Delete a container Write
container_stats Get container statistics Read
upload_file Upload a single file Write
bulk_upload Upload up to 100 files Write
list_files List files and folders at a path Read
get_document Retrieve full text of a document Read
delete_file Delete a file and its vectors Write
bulk_delete Delete up to 100 files Write
search_knowledge Semantic, keyword, or hybrid search Read

container_create

Create a new container for organizing documents. Use when setting up a new knowledge domain or project.

Parameters

Name Type Required Description
name string Yes Container name (lowercase alphanumeric and hyphens, 2-128 chars)
description string No Optional description for the container

Return Format

Container '<name>' created.

ID: <uuid>

Error Cases

  • Error: Container name must be 2-128 chars, lowercase alphanumeric and hyphens.
  • Error: Container '<name>' already exists.

Usage Example

"Create a container called 'project-docs' for storing our project documentation"

container_list

List all containers with document counts. Use to discover available knowledge bases before searching.

Parameters

None.

Return Format

Found 2 container(s):

- my-docs (15 files) — Project documentation
  ID: <uuid>
- research (8 files) — Research papers
  ID: <uuid>

Returns No containers found. when empty.

Error Cases

None.

Usage Example

"What knowledge bases are available?"

container_delete

Delete a container. MinIO containers must be emptied first. Filesystem/S3/Azure files are not deleted — only the index is removed.

Parameters

Name Type Required Description
containerId string Yes Container ID (UUID) or name

Return Format

Container '<name>' deleted.

Error Cases

  • Error: Container '<id>' not found.
  • Error: Container '<id>' is not empty. Delete all files first. (MinIO only)

Usage Example

"Delete the 'old-project' container"

container_stats

Get container statistics: document counts, chunk count, storage size, and embedding model info.

Parameters

Name Type Required Description
containerId string Yes Container ID (UUID) or name

Return Format

Container: my-docs
Type: MinIO
Documents: 15
Chunks: 342
Storage: 2.4 MB
Embedding model: text-embedding-3-small (1536 dims, 342 vectors)
Last indexed: 2026-03-15 10:30:00Z
Created: 2026-03-10 08:00:00Z

When any documents are processing or failed:

Documents: 15 (12 ready, 2 processing, 1 failed)

Error Cases

  • Error: Container '<id>' not found.

Usage Example

"How many documents and chunks are in the 'research' container?"

upload_file

Upload a file to be parsed, chunked, embedded, and made searchable. Provide either content (base64) or textContent (raw text), not both.

Parameters

Name Type Required Description
containerId string Yes Container ID (UUID) or name
content string No Base64-encoded file content. For binary files (PDF, DOCX, images). Mutually exclusive with textContent.
textContent string No Raw text content for text-based files (Markdown, TXT, CSV, JSON, etc.). Mutually exclusive with content.
fileName string Yes Original file name with extension
path string No Destination folder path (e.g., /docs/2026/). Default: /
strategy string No Chunking strategy: Semantic, FixedSize, or Recursive. Default: Semantic

Return Format

File 'readme.md' uploaded to /docs/readme.md and queued for ingestion.

Document ID: <uuid>
Job ID: <uuid>

The file will be parsed, chunked, and embedded in the background.

Error Cases

  • Error: 'fileName' is required.
  • Error: invalid filename '<name>' — must not contain path separators or '..' segments.
  • Error: file type '<ext>' is not supported. Supported types: ...
  • Error: Provide either 'content' or 'textContent', not both.
  • Error: Provide either 'content' (base64) or 'textContent' (raw text).
  • Error: Container '<id>' not found.
  • Error: 'content' must be valid base64-encoded data.
  • Write guard errors for read-only containers (S3, AzureBlob)

Usage Example

"Upload this markdown content as 'meeting-notes.md' to the 'project-docs' container"

bulk_upload

Upload up to 100 files in one call. Each file is parsed, chunked, and embedded. Returns per-file results.

Parameters

Name Type Required Description
containerId string Yes Container ID (UUID) or name
files string Yes JSON array of file objects. Each: {"filename":"name.txt", "content":"...", "encoding":"text|base64", "folderPath":"/optional/"}. Max 100.

Return Format

Uploaded 3 of 3 file(s) to container 'my-docs'.

All files queued for ingestion (parsing, chunking, embedding).

With failures:

Uploaded 2 of 3 file(s) to container 'my-docs'.

Failures:
- item[2]: missing 'filename'

Error Cases

  • Error: 'files' must be a valid JSON array of file objects.
  • Error: 'files' array must not be empty.
  • Error: Maximum 100 files per bulk_upload call.
  • Error: Container '<id>' not found.
  • Per-file: missing 'filename', missing 'content', invalid base64 content

Usage Example

"Upload these three research papers to the 'research' container"

list_files

List files and folders at a path within a container. Use to browse container contents before retrieving documents.

Parameters

Name Type Required Description
containerId string Yes Container ID (UUID) or name
path string No Folder path to list. Default: root /

Return Format

Contents of /:

[DIR]  docs/
[DIR]  images/
[FILE] readme.md (1,234 bytes) ID: <uuid>
[FILE] notes.txt (567 bytes) ID: <uuid>

Empty folders show (empty).

Error Cases

  • Error: Container '<id>' not found.
  • Error: Folder '<path>' not found in this container.

Usage Example

"What files are in the 'project-docs' container under /docs/?"

get_document

Retrieve a document's full text by ID or path. Returns extracted text for binary formats (PDF, DOCX, PPTX).

Parameters

Name Type Required Description
containerId string Yes Container ID (UUID) or name
fileId string Yes Document ID (UUID) or virtual path (e.g., /docs/readme.md)

Return Format

Document: readme.md
Path: /docs/readme.md
ID: <uuid>
Size: 1,234 bytes
Created: 2026-03-15 10:30:00Z
---
<full document text content>

Error Cases

  • Error: Container '<id>' not found.
  • Error: Container '<id>' could not be loaded. (rare — container deleted between checks)
  • Error: Document '<id>' not found in this container.
  • Error: Document '<name>' is still being ingested (status: Processing). Try again later.
  • Error: Document '<name>' failed ingestion: <message>
  • Error: No parser available for '<ext>' files.
  • Error: The backing file for '<name>' could not be read from storage.
  • Document '<name>' exists but contains no readable text content.

Usage Example

"Show me the contents of /docs/architecture.md in the 'project-docs' container"

delete_file

Delete a file and all its chunks and vectors. To update a file, delete it first then re-upload with upload_file.

Parameters

Name Type Required Description
containerId string Yes Container ID (UUID) or name
fileId string Yes File (document) ID to delete

Return Format

File 'readme.md' (ID: <uuid>) deleted.

If backing storage cleanup fails:

File 'readme.md' (ID: <uuid>) deleted from database, but the backing storage file could not be removed and may need manual cleanup.

Error Cases

  • Error: Container '<id>' not found.
  • Error: File '<id>' not found in this container.
  • Write guard errors for read-only containers (S3, AzureBlob)

Usage Example

"Delete the file with ID abc-123 from the 'project-docs' container"

bulk_delete

Delete up to 100 files in one call. Returns per-file success/failure results.

Parameters

Name Type Required Description
containerId string Yes Container ID (UUID) or name
fileIds string Yes JSON array of file (document) IDs to delete, e.g. ["id1","id2"]. Max 100.

Return Format

Deleted 3 of 3 file(s).

With warnings (backing storage cleanup failed):

Deleted 3 of 3 file(s).

Warnings (1):
- <id>: storage cleanup failed

With failures:

Deleted 2 of 3 file(s).

Failures:
- <id>: File '<id>' not found in this container.

Error Cases

  • Error: 'fileIds' must be a valid JSON array of strings.
  • Error: 'fileIds' array must not be empty.
  • Error: Maximum 100 files per bulk_delete call.
  • Error: Container '<id>' not found.

Usage Example

"Delete these three files from the 'old-data' container: id1, id2, id3"

search_knowledge

Search a container using semantic, keyword, or hybrid mode. Returns ranked document chunks with scores. Use when answering questions from stored knowledge.

Parameters

Name Type Required Description
query string Yes The search query text
containerId string Yes Container ID (UUID) or name to search within
mode string No Search mode: Semantic (vector), Keyword (full-text), or Hybrid (both). Default: Hybrid
topK integer No Number of results to return. Default: 10
path string No Filter results to a folder subtree (e.g., /docs/)
minScore number No Minimum similarity score threshold (0.0-1.0). Defaults to server setting.

Return Format

Found 3 result(s) in 45ms (mode: Hybrid):

--- Result 1 ---

When results are truncated by topK:

Showing 10 of 25 matching chunk(s) in 62ms (mode: Hybrid):

--- Result 1 ---
Score: 0.847
File: architecture.md
Path: /docs/architecture.md
Chunk: 2
DocumentId: <uuid>
Content:
<chunk text>

--- Result 2 ---
Score: 0.723
File: readme.md
Path: /readme.md
Chunk: 0
DocumentId: <uuid>
Content:
<chunk text>

Returns No results found. when no matches.

Error Cases

  • Error: Container '<id>' not found.
  • Query must not exceed <N> characters. (thrown as exception)
  • topK must be between <min> and <max>. (thrown as exception)
  • minScore must be between 0.0 and 1.0. (thrown as exception)

Usage Example

"Search the 'research' container for information about vector indexing strategies"

Write Guards

Write operations (upload_file, bulk_upload, delete_file, bulk_delete) are subject to per-connector permissions:

Connector Upload Delete Notes
MinIO Yes Yes Full read/write access
InMemory Yes Yes Full read/write access
Filesystem Configurable Configurable Per-container allowUpload / allowDelete flags (default: allowed)
S3 No No Read-only — synced from source
AzureBlob No No Read-only — synced from source

Write tools return a descriptive error when the container's connector blocks the operation.

Client Configuration

For MCP client setup (Claude Desktop, Claude Code, Cursor, etc.), see Using with Claude (MCP) in the main README.