/
MCP Connectors for Admins

MCP Connectors for Admins

Feature Flag Required
The MCP Connector Admin Panel is a feature-flagged capability and must be explicitly enabled for your organization. To activate this feature, please contact your Customer Success representative.

Overview

The MCP (Model Context Protocol) Connector Admin Panel allows administrators to connect external MCP servers to the platform, configure their tools, and make them available to spaces across the organization.

Screen Recording 2025-11-24 at 15.14.24.mov

 

Prerequisites

Required Permissions

To access and use the MCP Connector Admin Panel, you must have the following Zitadel authorizations:

  • connector.admin.read - View MCP connector configurations

  • connector.admin.write - Create and modify MCP connector configurations

The connectors admin panel is only visible to users with these permissions.

 

Connecting to an MCP Server

Step 1: MCP Servers Allow List

Before connecting, the server URL must be permitted according to the deployment's security policy. The policy is configured via environment variables:

Variable

Description

Required

Variable

Description

Required

MCP_POLICY_MODE

Security policy mode: STRICT, PATTERN, or UNRESTRICTED

Yes

MCP_ALLOWED_ENDPOINTS

Comma-separated list of allowed hosts or glob patterns

No

MCP_DENIED_ENDPOINTS

Comma-separated list of denied URLs or glob patterns

No

MCP Policy Modes Explained

  1. STRICT Mode

  • Only exact matches from the MCP_ALLOWED_ENDPOINTS list are permitted

  • Example: If MCP_ALLOWED_ENDPOINTS=api.example.com, only api.example.com will be allowed

  1. PATTERN Mode

  • Allows exact matches OR glob pattern matching (using * wildcard for subdomains only)

  • Example: if MCP_ALLOWED_ENDPOINTS=*.example.com,api.trusted.io, both api.example.com and api.trusted.io are allowed

  1. UNRESTRICTED Mode

  • Allows all endpoints except those explicitly listed in MCP_DENIED_ENDPOINTS

  • Use with caution in production environments

Step 2: Initiate Connection

The panel connects to the MCP server using an admin-only session to enumerate server capabilities.

This connection is not shared with users. Every user must connect to the server independently from the chat.

Unique does not support shared MCP connections.

Note: for now, MCP standard does not allow servers to advertise themselves without connecting to them first. Allowing capabilities discovery through .well-known URLs is on the MCP standard roadmap but has not been implemented yet. See: https://modelcontextprotocol.io/development/roadmap#server-identity

  1. Navigate to the MCP Connector Admin Panel

  2. Click the Add Connector button

  3. Enter the MCP server URL when prompted

  4. Click Connect

  5. Complete the OAuth authentication flow

image-20251124-142223.png
Adding a connector

 

Configuring a Connected MCP Server

Once successfully connected, you can configure the following settings:

1. Description

Provide a clear description of what this connector does.

This description will be visible to:

  • Space administrators when configuring their space

  • Space users viewing available tools

Best Practice: Write user-friendly descriptions that explain the connector's purpose and capabilities.

 

2. System Prompt (Server-Level)

It defines global instructions for the AI agent on how to think about and interact with this server, but must not contain any tool-specific information.

Important Guidance

  • The Server System Prompt is automatically injected into the global system prompt, meaning it affects the agent regardless of whether a specific tool of this server is used or not.

  • Do not include instructions on how specific tools should be used.

    If tools are disabled or changed, references in the system prompt remain and will confuse the agent.

  • All tool-specific instructions must be placed exclusively inside the Tools Configuration (this is the preferred method of guiding the agent).

  • Use this section only to explain the general purpose of the server and to define high-level reasoning guidelines.

Example Configuration:

  • MCP Connector: Unique Outlook MCP

  • System Prompt:

    ## Outlook MCP You can interact with everthing releated to emails. Check available tools for actions you can take. ### Error Handling When tools return errors, format like this: ```markdown ❌ **Error: [ERROR_TYPE]** [USER_FRIENDLY_ERROR_MESSAGE] <details><summary>Technical Details</summary> [TECHNICAL_ERROR_INFO if helpful] </details>

We strongly recommend optimizing prompts at the tool level first (see below). This typically provides the largest quality improvements. Only consider adding a server-level system prompt once tool-specific prompts are well-designed and you still need additional global guidance.

3. Tools Configuration

Per-Tool Configuration

For each enabled tool, you can customize:

Setting

Description

Setting

Description

Display Name

User-friendly name shown in the UI

System Prompt: Tool Usage Instructions

Instructions for how the agent should use this specific tool

System Prompt: Tool Response Format Instructions

Instructions for how the agent should format the tool's output

While tool system prompts are optional, they are strongly recommended to ensure the agent properly understands when to invoke the tool and how to format the output in a useful way for users.

Example Configuration:

image-20251124-142929.png
Example configuration of the List Emails tool for the Outlook MCP connector

  • MCP Connector: Unique Outlook MCP

  • Display Name: List Emails

  • Tool Usage Instruction: Returns the most recent emails from a folder. If the user does not specify a folder, use the inbox. Accept well-known names (inbox, sentitems, drafts, deleteditems) or explicit IDs from the tool list_mail_folders.

  • Tool Response Format Instructions:

Return emails as a *markdown-formatted list*, newest first. Each email must follow this compact structure: * Subject (bold, first line) - If a web link is available, make the subject a markdown link. * Metadata (second line) - From: Name <email> - Received: <timestamp> - Importance: Low|Normal|High - Read: Yes|No * Snippet (third line) - A short summary preview (max ~200 chars, plain text). * Separator - Use --- between emails.

 

Enabling Tools

  • Enable All: Toggle to enable all tools exposed by the MCP server

  • Selective Enable: Choose specific tools to make available

Only enabled tools will be visible to space administrators.

 

4. Organization-Wide Enablement

Use the Enabled slider to control visibility:

  • Enabled : The connector becomes visible to space administrators in the space configuration panel under Sources & Tools > MCP Tools.

  • Disabled : The connector remains configured but hidden from spaces

 Enabling a connector organization-wide does not automatically add it to existing spaces. Space administrators must still explicitly enable it in their space configuration.

 

Workflow Summary

MCP connector Workflow-2025-11-24-101609.png

 

Troubleshooting

Connection Failed

Issue: Cannot connect to MCP server

Possible Causes:

  • Server URL not in allow list

  • Policy mode restrictions

  • OAuth authentication failed

Solution:

  1. Verify the server URL matches the MCP_ALLOWED_ENDPOINTS configuration

  2. Check the MCP_POLICY_MODE setting

  3. Contact your platform administrator to update the allow list if needed

 

Connector Not Visible in Spaces

Issue: Space administrators cannot see the connector

Solution:

  1. Verify the connector Enable slider is turned on

  2. Confirm the connector configuration is saved

  3. Ask space admins to refresh the configuration panel

 

Additional Resources

 

Author

@Jeremy Isnard