MCP Connectors — Unique AI Documentation

MCP Connectors

This feature is currently in BETA. It may change before general availability, due to user and client feedback, but it targeted to be high quality and stable. Documentation may lag behind feature updates. Use in production environments at your own discretion. Please refer to our Upgrade and Release Process for more information.

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.

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
`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

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
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
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

Navigate to the MCP Connector Admin Panel
Click the Add Connector button
Enter the MCP server URL when prompted
Click Connect
Complete the OAuth authentication flow

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** |
| --- | --- |
| **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:

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:**

```markdown
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

Troubleshooting

Connection Failed

Issue: Cannot connect to MCP server

Possible Causes:

Server URL not in allow list
Policy mode restrictions
OAuth authentication failed

Solution:

Verify the server URL matches the MCP_ALLOWED_ENDPOINTS configuration
Check the MCP_POLICY_MODE setting
Contact your platform administrator to update the allow list if needed

Connector Not Visible in Spaces

Issue: Space administrators cannot see the connector