feat: add MCP server headers support #22718

[Cluas]

Summary

This PR adds support for custom HTTP headers in MCP (Model Context Protocol) tool providers, allowing users to configure additional authentication or configuration headers when connecting to MCP servers. This enhancement improves the flexibility of MCP tool integration by supporting various authentication methods and server-specific requirements.

close #22718

Key Changes

• Backend API Enhancement: Added headers parameter support in MCP tool provider creation and update endpoints
• Database Schema Update: Added headers column to tool_mcp_providers table with proper encryption/decryption
• Service Layer Updates: Enhanced MCP tool management service to handle custom headers
• Frontend UI Component: New HeadersInput component for managing custom headers in the MCP tool configuration modal

Technical Details

• Headers are stored as encrypted JSON in the database for security
• Backward compatible - existing MCP providers continue to work without headers
• Headers are automatically included in all MCP server requests
• Proper validation and error handling for malformed headers

Screenshots

Before	After

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran dev/reformat(backend) and cd web && npx lint-staged(frontend) to appease the lint gods

Testing

The changes include:

• Unit tests for the new header functionality

Breaking Changes

None. This is a backward-compatible enhancement that adds optional functionality.

Dependencies

No new external dependencies were added. The implementation uses existing encryption utilities and database infrastructure.

---

Note: This PR addresses the need for custom authentication headers in MCP tool providers, which is particularly useful for enterprise deployments requiring specific security headers or API keys.

[crazywoola]

Thanks for the PR, @Nov1c444 is reviewing this, however please link an existing issue or create a new issue in the description.

[Cluas]

#22718

[Nov1c444]

Could you please submit the frontend code together?

[Cluas]

Could you please submit the frontend code together?

Sorry, I accidentally forgot to submit the frontend code when resolving the conflict earlier.

[Cluas]

I have a question: when it comes to changes in migration versions, isn't it easy to have conflicts in different branches?
Like this,
https://github.com/langgenius/dify/blob/main/api/migrations/versions/2025_08_29_1534-b95962a3885c_add_workflow_app_log_run_id_index.py

[Nov1c444]

I have a question: when it comes to changes in migration versions, isn't it easy to have conflicts in different branches? Like this, https://github.com/langgenius/dify/blob/main/api/migrations/versions/2025_08_29_1534-b95962a3885c_add_workflow_app_log_run_id_index.py

That's indeed the case. We haven't found a better solution for this yet. We also have a dev environment, and during certain feature development, the migrations in dev become very troublesome due to various branch merges. One rather tricky approach is that we can first merge only the migrations into the main branch, and then merge the code logic into the main branch after it's completed. However, this is also very inflexible.

[Copilot]

Pull Request Overview

This PR adds support for custom HTTP headers in MCP (Model Context Protocol) tool providers, enabling users to configure additional authentication or configuration headers when connecting to MCP servers. This enhancement improves the flexibility of MCP tool integration by supporting various authentication methods and server-specific requirements.

• Backend API enhancement to support headers parameter in MCP tool provider endpoints
• Database schema update with encrypted headers storage and proper encryption/decryption handling
• Frontend UI component for managing custom headers in the MCP tool configuration modal

Reviewed Changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
web/service/use-tools.ts	Added headers parameter to MCP creation and update service calls
web/i18n/zh-Hans/tools.ts	Added Chinese translations for headers-related UI text
web/i18n/en-US/tools.ts	Added English translations for headers-related UI text
web/app/components/tools/types.ts	Added headers and masked_headers types to Collection and MCPServerDetail
web/app/components/tools/mcp/modal.tsx	Enhanced MCP modal with headers input functionality and state management
web/app/components/tools/mcp/headers-input.tsx	New component for managing custom headers with add/remove functionality
api/tests/.../test_mcp_tools_manage_service.py	Updated tests to include headers, timeout, and sse_read_timeout parameters
api/services/tools/tools_transform_service.py	Added timeout, sse_read_timeout, and headers to provider transformation
api/services/tools/mcp_tools_manage_service.py	Enhanced service with header encryption/decryption and MCP client integration
api/models/tools.py	Added encrypted_headers column and decryption/masking properties
api/migrations/...add_headers_to_mcp_provider.py	Database migration to add encrypted_headers column
api/migrations/...add_workflow_app_log_run_id_index.py	Updated down_revision reference for migration chain
api/core/tools/mcp_tool/provider.py	Updated provider to use decrypted headers from database
api/core/tools/entities/api_entities.py	Added timeout, sse_read_timeout, and headers fields to API entity
api/controllers/console/workspace/tool_providers.py	Added headers parameter support in MCP provider endpoints

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Nov1c444]

LGTM