Custom agents extend your AI Assistant with specialized skills and access to external tools. By connecting an MCP (Model Context Protocol) server, you can give your agent the ability to take real actions in third-party systems, like submitting ideas, creating tickets, or pulling data from internal services all from your AI assistant.

This article walks you through how to create a custom agent, connect it to an MCP server, and make it available to your users.

What is an MCP server?

MCP (Model Context Protocol) is an open standard that lets AI assistants securely connect to external tools and data sources. An MCP server acts as a bridge between your AI Assistant and another system, exposing a defined set of "tools" the assistant can use on behalf of your users.

In Flip, MCP servers power custom agents. When a user asks the AI Assistant something that matches the purpose of a custom agent, the assistant hands the request off to that agent, which then uses the connected tools to complete the task.

Example use cases

• Internal knowledge — Query a custom knowledge base, FAQ, or internal API that isn't covered by Flip's standard content sources.
• Idea and feedback collection — Let employees submit, search, and upvote ideas, suggestions, or feedback.
• Status and reporting — Pull data from internal dashboards, monitoring tools, or status pages.
• Reference lookups — Find product details, look up policy information, or surface reference data from internal systems.

Important: How authentication works

Flip currently supports API key authentication for MCP servers. This means every request from the AI Assistant, no matter which Flip user is chatting, is sent to the MCP server using the same shared API key.

In practice, today:

• The MCP server sees all requests as coming from a single account (the API key holder).
• Any action the agent performs in the connected system is technically carried out by that account.
• The MCP server cannot independently verify the identity of the Flip user behind a request.

This works well for read-only lookups and actions where the user's identity is metadata rather than a security boundary. For example, querying a knowledge base or submitting an idea.

This isn't suitable for actions that require per-user authentication or authorization. For example, booking time off in your HR system, accessing personal payslips, or anything where the connected system needs to enforce who's doing what. For those scenarios today, the MCP server has no way to confirm the Flip user's identity, and all actions would be attributed to the shared API key holder.

We're actively expanding authentication options. If your use case needs a different approach, for example, per-user OAuth so the connected system can identify each Flip user, please tell us how you'd like to authenticate. Your input helps us prioritize what comes next.

Before you start

• You'll need Root Admin permissions to create or edit custom agents.
• You'll need the URL of an MCP server that supports Streamable HTTP transport.
• If the MCP server requires authentication, have the header name and API key ready.
• You can create up to 10 custom agents per workspace.

Step 1: Open the Custom agent settings

1. Open the Admin Console.
2. In the left sidebar, go to AI Assistant → Custom agents.

3. Click Create Agent (or + New Agent if you already have agents set up).

   

Step 2: Add a connector

Each custom agent needs at least one connector, this is the MCP server that gives the agent its tools.

1. On the Connectors step, click + Add connector.

   

2. Fill in the connector details:
   • Name — A clear name for the connector (for example, "Idea Manager MCP Server").
   • MCP Server URL — The full URL of your MCP server.
   • Transport — Select Streamable HTTP.
   • Authentication — Select API Key if your server requires a key, or None for an open server.

3. If you selected API Key, enter the Header Name and API Key provided by your MCP server

   

4. Click Save.

Step 3: Set tool permissions

Once your connector is saved, Flip automatically discovers the tools exposed by the MCP server. By default, all tools are denied until you explicitly allow them.

1. Review the list of tools under Tool permissions.

2. Toggle each tool to Allow for any tool the agent should be able to use. You can also use the Allow / Deny dropdown at the top right to update all tools at once.

   

3. Click Next to continue.

Good to know: Only allow the tools your agent actually needs. Keeping unused tools denied helps the AI Assistant choose the right action and reduces unintended behaviour.

Step 4: Define the agent's identity

The Agent Details step is where you give your agent a name, purpose, and the instructions it should follow.

1. Click the Icon field to choose an icon. This icon appears in chat whenever the agent is active.

   

2. Enter an Agent name (for example, "Idea Manager").

3. Write a Description. Your AI Assistant uses it to decide when to activate this agent. Be specific about what the agent does and, just as importantly, what it shouldn't be used for.

   

    

4. Write Instructions for the agent. These tell the agent how to behave, its role, golden rules and any constraints. 

Tip: Click Write with AI to generate a description and instructions based on the connector and tools you've set up. Click Use this to insert it.

 

5. Click Next when you're done.

Step 5: Set user permissions

You can choose which user groups are allowed to interact with the agent. If you leave this empty, the agent uses the same user groups configured in your general AI Assistant settings.

1. Click the Add groups dropdown.
2. Search for and select the user groups that should have access.

Step 6: Activate and create the agent

New agents are created in Inactive status. To make the agent available to your users:

1. At the top of the agent page, click the Inactive status badge.

   

2. Select Active.
3. Click Create agent.

Test your agent

To check that everything is working as expected, open the AI Assistant in Flip and send a message that matches the agent's purpose. The assistant should activate your custom agent and use the connected tools to respond.

Manage your agents

From the Custom agent overview page you can:

• Edit an agent to update connectors, instructions, or permissions.
• Switch between Active and Inactive to control availability without deleting the agent.
• Delete an agent you no longer need.