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 when the system doesn't need to know who the individual user is, like searching public company knowledge or pulling status reports.

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.  In the Connectors step, open the connector whose tools you want to configure. If the agent has no connector yet, add one with Add connector.
3. Under Tool permissions, find the tool you want to configure.

On the tool row, select Needs approval. Users then have to confirm every call to that tool.

Note: Each tool has one of three settings. Always allow lets Ask AI use the tool without asking. Needs approval shows the user a Confirm action card before every call. Blocked hides the tool from Ask AI. New tools start as Blocked. Tools are grouped into Read-only tools and Other tools, and the menu in a group's header sets every tool in that group at once.

FAQ

• Can I change the details on the approval card?  
  No. The values on the card are read-only. Choose Deny, then ask Ask AI again with the corrected details.
• What happens if I deny an action?  
  That action does not run. Ask AI is told that you declined, and the conversation continues. You can ask again, for example with different details.
• Why am I being asked more than once?  
  Each tool call needs its own decision. If Ask AI wants to make several calls at once, the cards are stacked and you answer them one after another. Ask AI continues once you have decided on every card.
• Can I keep chatting while a card is open?  
  No. The message field is hidden until you choose Allow or Deny.
• What if I don't decide right away?  
  The request waits for your decision. When you come back to the chat, the card is still there.
• Does Allow mean the action succeeded?  
  No. Allow lets the call run, but the connected system can still fail. If it does, Ask AI either explains the problem in its reply or shows an error message. The approval card is not a confirmation that the action succeeded.
• Why don't I see an approval card?  
  An admin must set that tool to Needs approval, and the option must be enabled for your organisation. A tool set to Always allow runs without a card. A tool set to Blocked is not available to Ask AI.Review an Ask AI action before it runs
• Note: This feature is not yet marked as rolled out to production. Your organisation may not see it yet.

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.