[Proposal] Support user-scoped files generated by MCP tools

[geodanchev]

Summary

I would like to propose native support for files generated by MCP tools.

The goal is to allow an MCP server to create a file on behalf of the current LibreChat user and return it as a native downloadable attachment in the conversation, similar to how generated files are presented in ChatGPT.

This would support files such as:

• DOCX
• XLSX
• PPTX
• PDF
• CSV
• XML
• EML
• ZIP
• Images
• Other binary artifacts generated by MCP tools

I already have a working prototype for this flow, but I would first like to confirm the preferred architecture and scope with the LibreChat maintainers before opening a pull request.

Current limitation

MCP tools can generate files, but there is currently no standardized way for an external MCP server to:

1. Store a generated file through LibreChat.
2. Associate it with the authenticated user.
3. Associate it with the current conversation or assistant message.
4. Display it as a normal downloadable attachment in the chat.

As a result, MCP integrations currently need to use workarounds such as:

• Exposing an output directory through a separate web server.
• Uploading files to external cloud storage.
• Returning temporary or manually constructed URLs.
• Returning file paths that are not accessible to the LibreChat user.
• Embedding binary content directly in the MCP response.

These approaches do not provide consistent user isolation, storage, auditing, or attachment handling.

Proposed user experience

A user asks an MCP tool to create a document:

User:
Create an Excel report from this data.

The MCP server generates the file and returns it to LibreChat.

LibreChat then displays:

Assistant:
The report has been created.

[Download Report.xlsx]

The file should behave like any other LibreChat attachment:

• It belongs to the requesting user.
• It is visible in the conversation.
• It can be downloaded through LibreChat.
• It is stored through LibreChat’s configured storage backend.
• Another user cannot access it, even if they know the file ID.

Proposed flow

User requests a file
        ↓
LibreChat invokes an MCP tool
        ↓
MCP server generates the file
        ↓
MCP server transfers the file to LibreChat
        ↓
LibreChat stores it under the current user
        ↓
LibreChat associates it with the assistant message
        ↓
The file appears as a downloadable attachment

Generic MCP file artifact format

The MCP tool could return normalized file metadata after the file has been accepted by LibreChat.

Example:

{
  "result": {
    "message": "Document created successfully.",
    "file": {
      "file_id": "uuid-string",
      "filename": "Report.xlsx",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "bytes": 12345,
      "source": "local"
    }
  }
}

Multiple files could be supported later:

{
  "result": {
    "message": "Files created successfully.",
    "files": [
      {
        "file_id": "uuid-1",
        "filename": "Report.docx",
        "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "bytes": 12345
      },
      {
        "file_id": "uuid-2",
        "filename": "Data.xlsx",
        "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "bytes": 45678
      }
    ]
  }
}

The exact response format should follow the architecture preferred by the LibreChat maintainers.

User identity and ownership

LibreChat already supports passing user context to MCP servers through dynamic headers.

For example:

mcpServers:
  Office-documents:
    type: streamable-http
    url: http://mcp-office-documents:8958/mcp
    headers:
      X-User-Id: "{{LIBRECHAT_USER_ID}}"
      X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"

The generated file must be associated with the authenticated LibreChat user.

The implementation should not rely only on a user ID supplied as a normal MCP tool argument.

LibreChat should validate ownership when a file is:

• Downloaded
• Displayed
• Attached to a message
• Associated with a conversation
• Deleted
• Accessed through an API

Knowing a file ID should never be sufficient to access another user’s file.

Possible implementation approaches

I see several possible approaches.

Option A: Authenticated LibreChat upload endpoint

LibreChat exposes an internal service endpoint for trusted MCP servers.

Example:

POST /api/service/files

The MCP server authenticates with LibreChat and uploads the generated file.

LibreChat then:

1. Validates the MCP service.
2. Resolves the requesting user.
3. Validates the conversation when provided.
4. Stores the file through the existing file-storage abstraction.
5. Creates the file database record.
6. Associates the file with the user.
7. Returns normalized file metadata.

Option B: Short-lived scoped upload capability

When LibreChat invokes an MCP tool, it provides a short-lived upload URL or token.

The token could be scoped to:

• One user
• One conversation
• One tool call
• A maximum file size
• A short expiration time

This would avoid giving the MCP server a long-lived credential and would prevent it from selecting an arbitrary user.

Option C: MCP resource or artifact content

The MCP server returns the file as an MCP resource or binary content block, and LibreChat persists it through the existing artifact pipeline.

This may provide a more MCP-native implementation, but large binary payloads could make it less suitable for some files.

I would appreciate guidance on which approach best fits LibreChat’s architecture.

Message association

One implementation detail is that an MCP tool may finish before the corresponding assistant message has been saved.

LibreChat may therefore need a temporary attachment registry based on a message ID, tool-call ID, or request ID.

Possible lifecycle:

MCP tool finishes
        ↓
File metadata is stored temporarily
        ↓
Assistant message is persisted
        ↓
Pending file is attached to the message
        ↓
Temporary record is cleared

For multi-instance deployments, this may need a shared store rather than only an in-memory map.

Security requirements

The feature should include:

• Authentication between the MCP server and LibreChat
• User ownership validation
• Conversation ownership validation
• File-size limits
• MIME-type and extension validation
• Filename sanitization
• Path-traversal protection
• Temporary-file cleanup
• Protection against file-ID enumeration
• Rate limiting
• Audit logging
• Fail-closed behavior when user context is missing
• No public or unrestricted storage URLs

Storage compatibility

The feature should use LibreChat’s existing file-storage abstraction.

The MCP server should not need to know whether LibreChat stores files using:

• Local storage
• S3
• Azure Blob Storage
• Google Cloud Storage
• MinIO
• Another supported backend

The MCP server should transfer the file to LibreChat, and LibreChat should manage the final storage and authorization.

Relationship to existing requests

This proposal is related to existing discussions about generated Excel files and MCP file handling, but it addresses a specific missing flow:

MCP server → LibreChat → authenticated user

For example:

• Discussion Generate Excel file? #5171 asks about generating downloadable Excel files.
• Issue [Enhancement]: Temporary Downloadable File Links for MCP Integration #8060 discusses allowing MCP servers to access files uploaded to LibreChat.

Issue #8060 primarily covers:

LibreChat → MCP server

This proposal covers the reverse direction:

MCP server → LibreChat

Together, they would enable complete bidirectional file exchange:

User uploads file
        ↓
LibreChat sends it to MCP
        ↓
MCP processes or transforms it
        ↓
MCP returns a generated file
        ↓
LibreChat displays it to the user

Existing prototype

I already have a working prototype covering this use case for an MCP server that generates:

• DOCX
• XLSX
• PPTX
• EML
• XML

The prototype includes:

• User-context forwarding
• Service-to-service authentication
• Upload through LibreChat
• User-scoped file ownership
• Conversation association
• Native chat attachments
• Handling of MCP file-artifact responses
• Unit tests

However, I do not want to open a large pull request before confirming whether the architecture is acceptable to the LibreChat maintainers.

The goal is to contribute a generic MCP file-artifact capability, not an integration tied to one specific document server.

Suggested initial scope

To keep the first implementation small and reviewable, the initial version could support:

• One generated file per MCP tool response
• One canonical response format
• User ownership
• Conversation and message association
• Existing LibreChat storage backends
• Native attachment rendering
• File-size and filename validation
• Unit and integration tests

Multiple files and additional response formats could be added later.

Questions for the maintainers

Could a maintainer confirm:

1. Is support for files generated by MCP tools acceptable in principle?

2. Should generated files be persisted as standard LibreChat file records?

3. Which transfer mechanism is preferred?

   • An authenticated internal upload endpoint
   • A short-lived scoped upload URL or token
   • MCP resource or artifact content
   • Another existing LibreChat mechanism

4. Would you prefer this as one complete pull request or as several smaller pull requests?

5. Is there an existing artifact or attachment abstraction that should be extended rather than introducing a new MCP-specific path?

Once the preferred architecture and initial scope are confirmed, I can adapt the existing implementation and prepare the pull request accordingly.

[dvejsada]

@geodanchev That looks great. Hopefully this will be acceptable and implemented on LibreChat side and I wouůd very much welcome a PR to the mcp server.

[geodanchev]

Here is my pull request for the MCP ForLegalAI/mcp-ms-office-documents#85

[geodanchev]

Once we adopt the MCP, I'll submit my code review for LC. I'd love to see @danny-avila comments on the idea before we proceed.

[geodanchev]

Here is the PR with the changes needed for LC

[Aluriak]

Hello !

I am interested by this feature, but not for the same scope : i would like to send those generated files to the sandbox, so analysis may continue with dedicated tools.

It seems to me that currently any data sent to the codeapi sandbox needs to be first loaded in context window. This prevent real data analysis.

Thank you for your work.

[dvejsada]

@geodanchev Did we get any traction so far with LibreChat side of the changes?

[geodanchev]

#14405 Security review, There is a merge attempt. I'll take a look at it later when I have time.

[Aluriak]

Thanks for confirming the file_id mechanism. My remaining question is narrower : does the existing code-interpreter tool in LibreChat already accept a file_id as input without loading its content into the model's context, or would that require new work?

I will open a dedicated discussion about that, since it seems to be beyond that discussion scope.

[geodanchev]

Yes — in both of LibreChat's code-execution paths, files are referenced by file_id and provisioned directly into the execution environment rather than inlined into the model's context.
Can you confirm after you test this ?

[Aluriak]

Thanks, that's helpful and matches what I was hoping to hear.

One clarification on scope before I test: by "both of LibreChat's code-execution paths", do you mean the two paths built into LibreChat itself (e.g. the native Code Interpreter API and the Artifacts/execution path), or does that also cover custom/self-hosted sandbox backends plugged in through the same file_id mechanism (which is our case ; we run our own sandbox-runner) ? If it's specifically about the two native paths, I'd rather not assume it generalizes to a custom backend without checking.

Either way, I'll test this against our deployment and report back here with what we find.