> ## Documentation Index > Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Upload Knowledge Base Document > Use the upload_knowledge_base_document MCP tool on the DialNexa remote MCP server. Changes state - verify before retry Adds a real PDF or text FILE to a knowledge base and indexes it — the same import the dashboard upload performs. This is NOT a read-only action. Use it after create\_upload\_url (kind kb\_document, target\_id = kb\_id) once the user has uploaded the file: pass the upload\_id. In hosts that attach chat files to tools (ChatGPT), the host fills in `file` for a document the user attached; leave it alone otherwise. For text you already have in the conversation use upload\_knowledge\_base\_text instead — never base64-encode a PDF yourself. Titles must be unique within the knowledge base. ## Parameters | Name | Type | Required | Description | | ------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kb_id` | `string` | Yes | The knowledge base ID, e.g. kb\_abc123 | | `title` | `string` | Yes | Document title, unique within the knowledge base | | `description` | `string` | No | Optional one-line description of the document | | `upload_id` | `string` | No | Only for a file on a disk YOU control that is too large for file\_text (over \~50 KB): call create\_upload\_url with reveal\_url: true, PUT the bytes yourself from a machine with open internet access, then pass the upload\_id here. Never for a file the user attached in the chat (pass it as `file`), and never from a hosted chat sandbox such as ChatGPT code interpreter, which cannot reach the storage host. | | `file` | `object` | No | ALWAYS use this when the user attached a file in the chat: pass the attached file here and the host turns it into a download link for the server. Fastest path, any size. NEVER open, convert or base64-encode an attached file yourself. | | `file_name` | `string` | No | File name with extension (.pdf or .txt). Only needed with file\_base64; taken from the upload or attachment otherwise. | | `file_base64` | `string` | No | Base64 content for a SMALL .pdf/.txt only. Prefer upload\_id or the host attachment for anything real. | ## Complete input schema ```json theme={null} { "type": "object", "properties": { "kb_id": { "type": "string", "description": "The knowledge base ID, e.g. kb_abc123" }, "title": { "type": "string", "minLength": 1, "maxLength": 150, "description": "Document title, unique within the knowledge base" }, "description": { "type": "string", "maxLength": 500, "description": "Optional one-line description of the document" }, "upload_id": { "type": "string", "description": "Only for a file on a disk YOU control that is too large for file_text (over ~50 KB): call create_upload_url with reveal_url: true, PUT the bytes yourself from a machine with open internet access, then pass the upload_id here. Never for a file the user attached in the chat (pass it as `file`), and never from a hosted chat sandbox such as ChatGPT code interpreter, which cannot reach the storage host." }, "file": { "type": "object", "properties": { "file_id": { "type": "string", "description": "Host-side file id" }, "download_url": { "type": "string", "description": "Short-lived signed URL the host provides for the attached file" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "size": { "type": "number" } }, "required": [ "file_id", "download_url" ], "additionalProperties": false, "description": "ALWAYS use this when the user attached a file in the chat: pass the attached file here and the host turns it into a download link for the server. Fastest path, any size. NEVER open, convert or base64-encode an attached file yourself." }, "file_name": { "type": "string", "description": "File name with extension (.pdf or .txt). Only needed with file_base64; taken from the upload or attachment otherwise." }, "file_base64": { "type": "string", "description": "Base64 content for a SMALL .pdf/.txt only. Prefer upload_id or the host attachment for anything real." } }, "required": [ "kb_id", "title" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` ## Registered output schema ```json theme={null} { "type": "object", "properties": { "document_id": { "description": "ID of the created document" }, "knowledge_base_id": { "type": "string", "description": "The knowledge base it was added to, prefixed kb_" }, "title": { "type": "string", "description": "The document title as stored" }, "file_name": { "type": "string", "description": "The file name that was imported" }, "bytes": { "type": "number", "description": "Size of the imported file" }, "source": { "type": "string", "description": "How the file arrived: 'upload', 'attachment' or 'base64'" }, "status": { "type": "string", "description": "'ingested' once the file has been stored and indexed for retrieval" }, "note": { "type": "string", "description": "What happens next" } }, "required": [ "knowledge_base_id", "title", "file_name", "bytes", "source", "status", "note" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` ## Before you call * Connect and initialize the MCP client with OAuth or an API key for the intended workspace. * Provide the required parameters: `kb_id`, `title`. * Provide one file source: a host attachment, a completed upload\_id, or supported inline content. The optional file fields are alternatives; omitting all of them does not submit a file. See [MCP file uploads](/docs/mcp-tools/quickstart#mcp-file-uploads). ## Example MCP request Send `tools/call` after your client completes MCP initialization. Replace placeholder values with IDs and inputs from your workspace. For object and array parameters, follow the nested requirements in the parameter description instead of treating an empty value as complete. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "upload_knowledge_base_document", "arguments": { "kb_id": "kb_abc123", "title": "Example resource", "upload_id": "COMPLETED_UPLOAD_ID" } } } ``` Successful results include `structuredContent` and a text content block containing the same JSON. Check `isError` first, then read `structuredContent` or parse `content[0].text`. See [MCP responses and errors](/docs/mcp-tools/errors) for the full envelope and failure behavior. ## Verify the result Confirm the response is not marked `isError`. Call [List Knowledge Base Documents](/docs/mcp-tools/knowledge-base/list-knowledge-base-documents) to read the affected resource. Verify that the intended state is visible before making another change. ## Retry safety This tool changes workspace state. After a timeout, read the affected resource before retrying so you do not create duplicate or conflicting changes. ## Related MCP tools * [Create Upload URL](/docs/mcp-tools/uploads/create-upload-url): `create_upload_url` * [Upload Knowledge Base Text](/docs/mcp-tools/knowledge-base/upload-knowledge-base-text): `upload_knowledge_base_text` * [List Knowledge Base Documents](/docs/mcp-tools/knowledge-base/list-knowledge-base-documents): `list_knowledge_base_documents` * [Get Knowledge Base Document](/docs/mcp-tools/knowledge-base/get-knowledge-base-document): `get_knowledge_base_document` ## Related guides * [Connect to the DialNexa MCP server](/docs/mcp-tools/overview) * [Knowledge Base MCP tools](/docs/mcp-tools/knowledge-base/overview) * [MCP responses and errors](/docs/mcp-tools/errors)