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

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:

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

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

3. UNRESTRICTED Mode

• Allows all endpoints except those explicitly listed in MCP_DENIED_ENDPOINTS

• Use with caution in production environments

Step 2: Initiate Connection

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

Configuring a Connected MCP Server

Once successfully connected, you can configure the following settings:

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.

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:

  text

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

Context Forwarding

Context Forwarding controls whether the platform passes identifiers about the current user and the current conversation to the MCP server when one of its tools is called. The server can use them to scope its behaviour per user, per organization or per chat, for example to return only records that belong to the calling user, or to link results back to the conversation they came from.

The block sits in the General section of the connector's detail page, directly underneath the System Prompt field. It contains one switch per context group:

Both switches are off by default. Only enable what the server actually needs: every enabled group adds data that leaves the platform with each tool call to this server.

Declaring context requirements (for MCP server developers)

The declaration lives in the _meta object of each tool definition on the MCP server. Keys are split into required and optional:

"_meta": {
  "unique.app/context-requirements": {
    "required": ["unique.app/auth/user-id", "unique.app/auth/company-id"],
    "optional": ["unique.app/chat/chat-id", "unique.app/chat/assistant-id"]
  }
}

• Required keys must be forwarded for the tool to work. Until the matching group is enabled, the tool cannot be enabled in Tools Configuration: its switch is disabled and a warning icon explains which group to enable (for example, "Enable Auth in Context Forwarding above to use this tool.").

• Optional keys are forwarded when the matching group is enabled, but never prevent the tool from being used.

Only declare the keys listed in the table above. A tool that requires a key the platform does not provide can never be enabled. If the key belongs to a namespace the platform does not know, the block also shows an Unsupported context namespaces detected warning that lists the affected tools. To fix this, remove the key from the tool's declaration or move it to optional.

If you build your server in Python with Unique's unique-mcp package, declare the requirements with ContextRequirements and the MetaKeys constants:

from fastmcp.tools import tool
from unique_mcp import ContextRequirements, MetaKeys, merge_tool_meta


@tool(
    name="search",
    description="Search the knowledge base.",
    meta=merge_tool_meta(
        {"unique.app/icon": "search"},
        ContextRequirements(
            required=[MetaKeys.USER_ID, MetaKeys.COMPANY_ID],
            optional=[MetaKeys.CHAT_ID],
        ),
    ),
)
async def search(query: str) -> str: ...

The mcp_search tutorial server is a complete working example.

After changing a tool's declaration, click Refresh Tool Settings in Tools Configuration (or reconnect the connector) so the platform picks up the new requirements. The Context Forwarding block then shows the declared groups.

How the MCP server receives the context

Forwarded values are not sent as HTTP headers. They are sent in the _meta field of the MCP tools/call request (params._meta), as defined by the MCP specification:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": { "query": "Q3 revenue" },
    "_meta": {
      "unique.app/auth/user-id": "<user id>",
      "unique.app/auth/company-id": "<company id>",
      "unique.app/chat/chat-id": "<chat id>",
      "unique.app/chat/user-message-id": "<message id>",
      "unique.app/chat/assistant-id": "<space id>"
    }
  }
}

A key is only included when a value is available for that call. For backward compatibility, the request can also contain the unprefixed keys userId, companyId, chatId and messageId. New servers should read the namespaced unique.app/… keys.

Tools Configuration

Per-Tool Configuration

For each enabled tool, you can customize:

Example Configuration:

• 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

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

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:

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

Context Forwarding Block Not Visible

Issue: The connector's detail page shows no Context Forwarding block under the System Prompt field.

Cause: None of the server's tools declare unique.app/context-requirements in their tool _meta. The block is only shown for servers that ask for context, so this is expected for any server that has not declared requirements.

Solution:

1. Add a unique.app/context-requirements declaration to at least one tool on the MCP server (see 3. Context Forwarding above for the format).

2. Click Refresh Tool Settings in Tools Configuration, or reconnect the connector, so the platform picks up the new tool definitions.

3. Reload the connector's detail page. The block appears with a switch for each declared group.

Tool Cannot Be Enabled

Issue: A tool's switch in Tools Configuration is disabled and shows a red warning icon.

Cause: The tool requires context that is not being forwarded. Either the matching Context Forwarding group is switched off, or the tool requires a key the platform does not provide.

Solution:

1. Hover over the warning icon to see which group is missing, enable that group in Context Forwarding and save.

2. If the Context Forwarding block shows Unsupported context namespaces detected, the tool requires a key the platform cannot forward. The MCP server's developer must remove that key from the tool's declaration or make it optional.

Additional Resources

• Managing MCP Tools in Spaces

• MCP Specification