Build your first MCP agent

An agent that calls real tools on an MCP server — declared in the flow, granted on the board, and traceable call by call.

What an MCP server is, and what it is not#

An MCP server is a separate program that exposes a set of tools over the Model Context Protocol. It might be in front of your CRM, your ticketing system, a database or a filesystem. It is not part of Symphonix, it is not started by an agent, and it has its own lifetime, its own address and its own credentials.

The agent runtime is the deployed project. It holds the flow, the generated client for each declared server, and the model calls. When a tool is called, the agent connects to the MCP server, makes the call, and gets a result back. That is the whole relationship.

Five screens say “MCP”, and they are five different things#

This is the single most common source of confusion, so it is worth two minutes before you touch anything. These are the names the product itself uses.

1 · Register the server in the catalogue#

This is done once for the organisation, by somebody with agents.manage. Every agent then draws on it.

1. in the Control Panel Sign in to the Control Panel and open Settings, then the MCP servers tab.
2. in the Control Panel Add an entry. What it holds is where the server is: a name that agents will use, a transport (http or stdio), and either a url for http or a command for stdio.
3. in the Control Panel For the credential, give the name of the environment variable that holds the token — not the token. The board stores the name and never the value, which is why it cannot authenticate to the server itself.
4. in the Control Panel Save the entry. Note the name exactly: it is the string your flow will declare.

2 · Find out what tools the server has#

1. in the Control Panel If an agent on this installation has already connected to this server, open the server and look at its Tools tab. It lists what the server offered, in the server's own names, against what the flows declare — and names any disagreement.
2. in the Control Panel If nothing has connected yet, that tab is empty, and it is empty for a correct reason rather than a broken one. Take the tool names from the server's own documentation for now; they will appear here once your agent has run.

3 · Declare the server in your flow#

Back in the Studio. The declaration is the ceiling: a server exposing twenty tools gives this flow only the ones listed.

1. in the Studio Open your flow and select the MCP SERVERS tab on the right-hand panel.
2. in the Studio Add the server by the name you registered, and list the tools this flow may call. In the file it looks like this:

   "requires": {
     "mcp": {
       "crm": {
         "describe": "The customer system. Read-only except for openTicket.",
         "tools": [
           "findCustomer",
           { "name": "openTicket", "remote": "create_ticket",
             "describe": "Raises a support ticket.",
             "inputs": { "about": { "type": "string", "required": true, "label": "What is wrong" } } }
         ]
       }
     }
   }

   Copy

3. in the Studio Note three things in that example. The tool list is the permission. remote is the name the tool has on the server, for when it differs from the name your flow wants — which is how two servers that both expose search are told apart. And inputs says what the tool takes.

4 · Configure the work node#

This is where the agent actually uses the tools. One node does it.

1. in the Studio Add a node and set its KIND to work.
2. in the Studio Set PROMPT to what you want it to achieve — not to a procedure. The model decides which tools to call.

   { "id": "answer", "type": "work",
     "prompt": "Answer the question using the customer system.\n{{history}}\nQuestion: {{question}}",
     "tools": ["crm"],
     "output": "answer" }

   Copy

3. in the Studio Set tools. It takes server names — meaning every tool the flow declares on that server — or individual tool names, to give this node less than the flow has.
4. in the Studio Set OUTPUT to the channel the answer goes in.
5. in the Studio Optionally set rounds, which caps how many times round the loop. The default is 8. Reaching it fails the run by name rather than returning half an answer.
6. in the Studio Optionally set approve, listing tools that need a person first. The run pauses at that call and carries on with the model's own work when the answer comes back.

The two execution patterns, and which one the platform gives you#

Pattern 1 — ReAct, or dynamic tool calling#

The model is handed the tools and calls them itself, one after another, until it has an answer. Directly supported: this is exactly what a work node is (DSL 0.24). You have just built one. Released

Use it when the work is a handful of lookups whose order depends on what comes back, and when a fresh answer each time is fine. It is the reference's own recommendation for most tool use, and it is one node.

What you give up: the plan is never visible before it runs, a failure halfway through leaves you reasoning about a transcript, and the cost of a turn is whatever the model decided to do.

Pattern 2 — Plan and Execute#

A planner writes a task list, a loop picks the next task, an executor runs it against the tools, the result is evaluated into task state, and the loop continues, replans or finishes.

Use it when the plan should be visible before anything runs, when each task deserves a fresh context, when one failure should leave only its dependants unattempted, and when replanning should be a decision in the open rather than an emergent behaviour.

What it costs. The real cost is not the language, it is the state contract: a plan is a list of tasks with dependencies and outcomes, and the shape of a task has to be settled once — in the channel's own description — before several generated handlers are written against several readings of it.

5 · Test the tool calls before deploying#

1. in the Studio Check the PROBLEMS bar. A flow that declares an MCP server needs nothing else — the generated scaffold brings the protocol package in. A flow that only talks about MCP in prose, without declaring a server, is told to add the package by hand, which is the sign you have described a server where you should have declared one.
2. in the Studio Press ▶ Play and ask something that needs a tool.
3. in the agent's chat Watch what happens. A tool call that is missing a required input shows you a form — that is the designed behaviour, not a failure. A tool listed in approve pauses and waits for a person.
4. in the Studio Use the history view to see the calls themselves. Its filter includes MCP tool calls as a category of its own.

6 · Deploy it#

Exactly as in the first tutorial: Deploy all…, choose a folder, tick fill a new .env from Settings, npm install afterwards and put it on the board, then Deploy.

7 · Switch the tools on, on the board#

This is the step people miss, and missing it looks exactly like a broken agent.

1. on the machine Start the deployed agent and let it register.
2. in the Control Panel Open the Control Panel, find the agent, and open its MCP tab. This is the subscription — which of the declared tools this particular agent may call.
3. in the Control Panel Switch on the tools this agent should have. You can only narrow what the flow declared; nothing here can widen it.
4. in the Control Panel Save. The change reaches the running agent over its socket — the agent does not need restarting.

8 · Verify the calls are really happening#

1. in the agent's chat Open the agent's own address and ask a question that needs a tool.
2. in the Control Panel Open the agent's runs on the Control Panel and find that conversation. Each tool call appears as its own step, with what was sent and what came back.
3. in the Control Panel Open the MCP server's Tools tab. It should now be filled in — your agent connected and reported what the server offered. If the server offers tools your flow does not declare, this is where the difference is named.

Diagnosing permission and connection failures#

What to do next#

• Deploy and monitor — the lifecycle, health, and reading a run properly.
• Multi-agent — when one agent should call another instead of growing more tools.
• Human in the loop — approve in full, and who gets asked.
• The DSL reference — requires.mcp and work in their own words.