Custom MCP (Message Control Protocol) Services#

Concept#

Custom MCP services in this project are user-defined integrations that extend the system's capabilities by connecting to external endpoints using the Message Control Protocol. Each MCP service is treated as a "tool" of type mcp and is managed entirely within the frontend UI. These services allow users to route specific requests or tasks to remote servers that implement the MCP interface, enabling custom workflows or data retrieval beyond the built-in tools.

Adding and Removing Custom MCP Services#

Custom MCP services are managed through the UI, which provides a dialog for adding, editing, and removing services. Each service requires a label, a server URL, an approval requirement, an optional list of allowed tools, and a new authorization configuration. The process is as follows:

Adding a Service:

1. Open the MCP Services dialog in the UI.
2. Fill in the required fields:
   • Label: A unique name for the service.
   • Server URL: The endpoint for the remote MCP service (must be a valid URL).
   • Require Approval: Set whether the service requires approval for use (always or never).
   • Allowed Tools: (Optional) Comma-separated list of tools permitted to use this service.
   • Authorization: Choose how the service should be authorized. The following modes are available:
     • None: No authorization is sent to the MCP server.
     • Static Token: Enter a static token string to be sent with requests.
     • User Data (Encrypted): Grant consent to share user data scopes with the MCP server. The system uses OpenID Connect discovery to fetch supported scopes from the server's /.well-known/openid-configuration endpoint. Users must explicitly grant consent before any data is transmitted. If the server doesn't provide scope definitions, the system falls back to common scopes (name, email, preferred_username, sub, affiliations) present in the user's data. All data is end-to-end encrypted so only authorized FH servers can decrypt it.
3. Save the service. This creates a new Tool.Mcp object and adds it to the internal tools map, updating the application state.

Removing a Service:

1. Open the MCP Services dialog.
2. Locate the service in the list.
3. Click the delete button next to the service. This removes the service from the tools map and disables it in the application state.

Example Configuration Object:

{
  "type": "mcp",
  "server_label": "DeepWiki",
  "server_url": "https://mcp.deepwiki.com/mcp",
  "require_approval": "never",
  "authorization": {
    "mode": "user-data",
    "userData": {
      "scopes": [
        { "scope": "name" },
        { "scope": "email" }
      ],
      "consentGranted": true
    }
  }
}

User Data Authorization Details:

• When "User Data (Encrypted)" mode is selected, the system uses OpenID Connect discovery to fetch supported scopes from the server's /.well-known/openid-configuration endpoint. The UI displays these scopes (with localized descriptions if available) rather than arbitrary user fields.
• Users must explicitly check a consent checkbox before any data is transmitted. If consent is not granted, no authorization token is generated.
• The data is encrypted in the browser using the MCP server's public key (fetched from the JWKS endpoint). The encrypted JWT includes iat (issued at) and exp (expiration time) claims, with a 6-hour lifetime. The encryption algorithm is RSA-OAEP.
• Only authorized FH servers can decrypt the data. No user data is sent to the MCP server unless the user explicitly grants consent.
• Users can revoke consent at any time by editing the service and unchecking the consent checkbox or switching to another authorization mode.
• If the server doesn't support OpenID Connect discovery or doesn't provide scope definitions, the system falls back to common scopes (name, email, preferred_username, sub, affiliations) present in the user's data.
• Old configurations with selectedFields are automatically migrated to the new scopes format.

Source

OpenID Connect Discovery and Authentication#

The MCP authentication system uses OpenID Connect discovery to automatically configure user data authorization. When a user selects "User Data (Encrypted)" mode, the system performs the following steps:

Discovery Process:

1. Fetches the server's OpenID Connect configuration from /.well-known/openid-configuration
2. Extracts required fields from the discovery document:
   • scopes_supported: An array of scope strings that define what user data the server expects
   • jwks_uri: The endpoint to fetch the public key for encryption
3. Fetches the JWKS endpoint to obtain the public key for encrypting user data
4. If discovery fails or the server doesn't support it, the configuration remains unchanged and the system logs a warning

Scope Configuration:

• Server-defined scopes are presented to the user as read-only items in the UI
• Each scope may show a translated description and the current user's value for that scope
• When server-defined scopes are present, the "None" and "Static Token" options are disabled to enforce the server's authentication requirements
• Scope definitions are stored as objects with a scope property (string)

JWT Token Creation:

• The encrypted JWT token includes iat (issued at) and exp (expiration time) claims
• Token lifetime is 6 hours from issuance
• Encryption uses the RSA-OAEP algorithm with A256GCM content encryption
• The token is only created if the user has granted consent

Error Handling:

• If OpenID discovery fails, the system logs a warning and keeps the current configuration
• If JWKS fetch or key import fails, the system throws an error during authorization
• Encryption errors use localized error messages from i18n

Source

Local vs. Remote MCP Services#

The current implementation supports only remote MCP services. Every MCP service must specify a server_url, which points to an external endpoint. There is no support for local MCP services (i.e., services running within the same process or environment as the UI). The design assumes all MCP integrations are remote by nature, and the UI enforces this by requiring a URL for each service. There is no backend or proxy logic for MCP; all configuration and invocation are handled in the frontend, and all MCP calls are routed to remote endpoints only.
Source

OpenAI Responses API Support Limitations#

When a user initiates a response, all enabled tools—including custom MCP services—are forwarded directly to the OpenAI responses API. The system does not perform any additional validation or proxying for MCP services. As a result, the ability to use remote MCP services is limited by what the OpenAI responses API supports. There is no explicit handling or error reporting for unsupported MCP services beyond what the API itself provides. Local MCP endpoints or extended functionalities are not present or supported in the current system.
Source

UI Example#

The UI presents a dialog for managing MCP services, where users can add, edit, or remove services. Each service appears in a list with options to enable/disable, edit, or delete. The dialog enforces required fields and updates the application state accordingly.

Authorization Controls:

• When adding or editing a service, the dialog includes an "Authorization" section where users can choose between:
  • None: No credentials or user data are sent.
  • Static Token: Enter a token string to be sent with requests.
  • User Data (Encrypted): Grant consent to share user data scopes with the MCP server. The system fetches scopes via OpenID Connect discovery and displays them as read-only items with localized descriptions.
• If "User Data (Encrypted)" is selected, a privacy notice is shown, and the user can open a dialog with more details about encryption and data handling.
• Scopes are displayed as read-only items (not checkboxes for individual fields). Each scope may show a translated description and the current user's value for that scope.
• A consent checkbox is required and shown separately. Users must explicitly check it to authorize data transmission.
• When server-defined scopes are present, the "None" and "Static Token" options are disabled to enforce the server's authentication requirements.
• Consent can be revoked by editing the service and unchecking the consent checkbox or switching to another mode.

Privacy and Security:

• User data is only sent to MCP servers if the user explicitly grants consent via the consent checkbox.
• All user data sent is encrypted using the RSA-OAEP algorithm with A256GCM content encryption. Only authorized FH servers can decrypt it. OpenAI and other third parties cannot read the data.
• The encrypted JWT includes iat (issued at) and exp (expiration time) claims, with a 6-hour token lifetime.
• The UI provides clear information about what scopes are shared and how the data is protected.
• The system uses OpenID Connect discovery to fetch scope definitions and encryption keys from the MCP server.

Source