MCP Tools Reference

Complete API reference for all Cyborg MCP tools.

upload_docs

Upload documentation files to the Cyborg backend for processing and indexing.

Parameters

Parameter	Type	Required	Default	Description
publishableKey	string	No	env var	Cyborg publishable key (falls back to CYBORG_PUBLISHABLE_KEY env var)
filePaths	string[]	Yes	-	Array of glob patterns for files to upload
docsDir	string	No	./cyborg-docs	Base directory for state file location
documentType	'markdown' | 'text'	No	markdown	Document type for backend processing

Example

upload_docs({
  "filePaths": ["./docs/**/*.md", "./README.md"],
  "docsDir": "./docs",
  "documentType": "markdown"
})

Response

{
  "success": true,
  "uploaded": [
    { "path": "getting-started.md", "documentId": "doc_abc123" },
    { "path": "api-reference.md", "documentId": "doc_def456" }
  ],
  "failed": []
}

Error Response

{
  "success": false,
  "uploaded": [
    { "path": "getting-started.md", "documentId": "doc_abc123" }
  ],
  "failed": [
    { "path": "large-file.md", "error": "File too large (max 10MB)" }
  ]
}

---

sync_docs

Detect changes in documentation and sync them with the backend efficiently.

Parameters

Parameter	Type	Required	Default	Description
publishableKey	string	No	env var	Cyborg publishable key (falls back to CYBORG_PUBLISHABLE_KEY env var)
docsDir	string	No	./cyborg-docs	Documentation directory to sync
dryRun	boolean	No	false	Preview changes without uploading

Example

sync_docs({
  "docsDir": "./docs",
  "dryRun": true
})

Dry Run Response

{
  "success": true,
  "dryRun": true,
  "changes": {
    "toUpload": ["new-guide.md"],
    "toUpdate": ["getting-started.md"],
    "unchanged": ["api/useChat.md", "api/useCyborg.md"],
    "deleted": ["old-file.md"]
  }
}

Full Sync Response

{
  "success": true,
  "uploaded": [
    { "path": "new-guide.md", "documentId": "doc_xyz789" }
  ],
  "updated": [
    { "path": "getting-started.md", "documentId": "doc_abc123" }
  ],
  "unchanged": 2,
  "deleted": ["old-file.md"]
}

Change Detection Algorithm

The sync process uses a 3-pass algorithm:

1. Pass 1 - Local Hash Comparison: Reads local files, calculates SHA-256 hashes, compares against stored hashes
2. Pass 2 - Backend Comparison: Fetches backend hashes only for potentially modified files
3. Pass 3 - Upload/Update: Uploads new files and updates modified files

---

update_doc

Update a single documentation file on the backend.

Parameters

Parameter	Type	Required	Default	Description
publishableKey	string	No	env var	Cyborg publishable key (falls back to CYBORG_PUBLISHABLE_KEY env var)
documentId	string	Yes	-	ID of the document to update
content	string	Yes	-	New content for the document
filePath	string	No	-	Optional file path to read content from

Example - Direct Content

update_doc({
  "documentId": "doc_abc123",
  "content": "# Updated Guide\n\nNew content here..."
})

Example - From File

update_doc({
  "documentId": "doc_abc123",
  "filePath": "./docs/getting-started.md"
})

Response

{
  "success": true,
  "documentId": "doc_abc123",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Error Response

{
  "success": false,
  "error": "Document not found",
  "documentId": "doc_abc123"
}

---

delete_doc

Delete a documentation file from the backend.

Parameters

Parameter	Type	Required	Default	Description
publishableKey	string	No	env var	Cyborg publishable key (falls back to CYBORG_PUBLISHABLE_KEY env var)
documentId	string	Yes	-	ID of the document to delete

Example

delete_doc({
  "documentId": "doc_abc123"
})

Response

{
  "success": true,
  "documentId": "doc_abc123",
  "deletedAt": "2025-01-15T10:30:00Z"
}

Error Response

{
  "success": false,
  "error": "Document not found",
  "documentId": "doc_abc123"
}

---

Common Parameters

All tools accept these common parameters:

Parameter	Type	Description
publishableKey	string	Your Cyborg publishable key. If not provided, falls back to the CYBORG_PUBLISHABLE_KEY environment variable.

State File

All tools that modify documents update the .cyborg-state.json file:

{
  "apiUrl": "https://api.cyborgsdk.dev/api/v1",
  "lastSyncedAt": "2025-01-15T10:30:00Z",
  "files": {
    "getting-started.md": {
      "documentId": "doc_abc123",
      "contentHash": "sha256:e3b0c44298fc...",
      "syncedAt": "2025-01-15T10:30:00Z"
    }
  }
}

Error Handling

All tools return a consistent error format:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common error types:

• Authentication failed - Invalid or missing API key
• Document not found - Document ID doesn't exist
• File too large - File exceeds size limit (10MB)
• Invalid file type - Unsupported document format
• Rate limited - Too many requests, try again later

Next Steps

• Resources Reference - Available MCP resources
• Upload Docs - Initial upload guide
• Sync Docs - Keeping docs in sync