MCP in Perfox
When a customer asks "what's my current balance?", your agent has to get the answer from somewhere real. MCP (Model Context Protocol) is how: your agent calls a tool on your server, gets the result, and uses it in its reply. Perfox shows MCP servers as Integrations.
This page is for builders who want to connect their own systems to a Perfox agent. You'll see how a call works, where integrations attach on the canvas, and what Perfox does on every call.
Two directions
This page covers the outbound direction — your agent calling tools on your server. There is also an inbound direction: any MCP-capable assistant can connect to Perfox's own Platform API over MCP to create and publish agents, upload Knowledge Base files, and manage customers and conversations. Explore those tools in the MCP Explorer.
How your agent calls your server
Perfox connects to your MCP server as a standard MCP client over HTTPS, at the single address you register. You build the server to the open MCP standard; Perfox does the rest:
| Step | When | What Perfox gets |
|---|---|---|
| Connect | When you add the server, and whenever it is re-checked | A handshake confirming your server speaks MCP. |
| Discover tools | When you add the server, when you click Rediscover, and automatically when an agent uses a server whose saved tool list is more than an hour old | Each tool's name, description and expected inputs. |
| Call a tool | Whenever the agent decides to use one of your tools in a conversation | The tool's result, which the agent uses in its reply. |
You never register tools by hand — Perfox reads them from your server. A clear tool description (what it does and when to use it) is what makes the agent pick the right tool.
Worked example — Asha connects Acme Diagnostics' booking system
Setup. Asha is building a patient-support agent. Acme's booking system exposes a get_report_summary tool on an MCP server at https://api.acme-diagnostics.com/mcp.
Action. In Connect → Integrations she opens Browse → Add custom server, enters the address and its API key, and clicks Add Integration. On her agent's canvas she adds an Integration sub-node to the AI Agent and picks the new server.
Result. When Priya, a patient, asks "can I get a summary of my latest blood work?", the agent calls get_report_summary and replies with a plain-language summary.
What just happened. Perfox discovered the tool when Asha added the server, attached her API key to the call, told the server which conversation and customer the call was for, and recorded the call and its result in the conversation. Acme's server needed nothing Perfox-specific.
Writing a server of your own: Building Your Own MCP Server.
What Perfox does on every call
- Only the tools you chose. The agent can call only the tools of the integrations attached to it — and, if you picked specific tools on the Integration sub-node, only those.
- Your credentials, attached at call time. The secret you entered is stored encrypted and added to each call, never shown to the agent or the customer. Change it with Edit connection and every agent uses the new one immediately — no agent edits.
- Who the call is for, and who is calling. Each call carries the conversation, the channel, whatever identity the conversation holds (name, phone, email, your own customer ID, Perfox's own customer ID outside phone calls), and which agent is making the call, so your server can recognise the customer without asking again and decide what each agent may do. See Building Your Own MCP Server.
- Timeouts, and no blind re-sends. Each call waits up to the connection's Timeout (30 seconds by default). A call is retried only when it provably never reached your server (for example the connection was refused). A call that timed out or got an error back is not re-sent, because your server may already have acted on it — so a slow server never receives the same booking twice. A rejected credential is reported as an authentication error so you know to fix it.
- An idempotency key on every call. Each tool call carries an
Idempotency-Keyheader, the same on every delivery attempt of that call, so your server can recognise a repeat and answer it without acting twice. See Building Your Own MCP Server. - Tool text checked for prompt injection. When Perfox reads your server's tools, it checks their names, descriptions and inputs for text that tries to steer the agent. A tool that looks dangerous is withheld from agents until an admin approves it — see Registering.
- Oversized results handled. If a tool returns more than the AI model can read at once, the connection's Oversized results setting decides what happens — see Registering.
- Every call recorded. Each tool call and its result appear in the conversation history and in the agent's runs, so you can see exactly what was asked and what came back.
Where integrations attach on the canvas
Connect an MCP server to an AI Agent with the Integration sub-node: add it to the AI Agent's Integration port and pick one of your connected servers. Add several Integration sub-nodes to combine servers — a CRM, a billing system and your own domain server, all on one agent.
Each Integration sub-node points at one server and, optionally, a list of the tools to allow. Agents use the tool list Perfox saved for the server. Perfox refreshes that list on its own once it is more than an hour old (the turn that notices uses the saved list; the next turn gets the new one). To make a new tool available straight away, click Rediscover on the server's card.
What's built in
Many everyday actions don't need an MCP server at all: answering from your documents (the Knowledge port), and sending email, SMS or WhatsApp, updating a sheet or handing off to a person (Action nodes). See What's built in.
Next steps
- Registering an MCP server — connect a catalog provider or your own server.
- Building Your Own MCP Server — the contract your server implements.
- Integration sub-node — choose which server and tools an agent gets.
- What's built in — actions that need no server.