Set up an MTConnect Agent in three or so steps

Hi! This article is very old and outdated. You might consider checking out this newer article on installing the MTConnect Agent.

In the past few months, I’ve written about MTConnect on several occasions. I’ve even posted a walkthrough for installing the MTConnect agent on a Debian system.

Lately I’ve seen a few visitors searching for information on MTConnect agent setup. I don’t really have a walkthrough for completely setting up the MTConnect agent, but I thought I’d post a very brief overview.

Step 0: Get your tool ready for MTConnect

This step takes the most work, because it’s the least standardized part of the process. Typically, the MTConnect Agent collects data from a component called an Adapter. An adapter might be hardware, like an adapter box. Or for newer controls, it might be a low-cost software option.

Some adapters work with proprietary APIs, such as FOCAS. Some collect CNC data through a PLC via Modbus. Some translate from another existing data provider, such as OPC.

A few toolbuilders have been very supportive of the MTConnect standard, and provide fully-featured adapters. For some other CNCs, the community has stepped up to fill this need.

Whatever the case, you’ll need to obtain an MTConnect adapter for your CNCs. Check with your distributor or toolbuilder first.

Step 1: Get the Agent source code

The MTConnect Institute provides C++ source code for the Agent on GitHub The GitHub repository contains a very complete explanation of how to build the agent, as well as how to configure it. Since the README file is updated whenever a significant change occurs to the code, you should consult it for the latest information on building and configuration options.

Near the top of the page, on the toolbar, you have several options. Click on the “ZIP” button to download the source code as a ZIP file.

Step 2: Build the Agent

To build the Agent, you’ll need CMake, which is downloadable here.

If you’re on a Windows machine, you’ll also need a C++ compiler installed on your system, such as the one that comes with Visual Studio. (You’ll need this on a Linux box as well, but you’re much more likely to already have one on your system.)

Extract the zipped source code and run cmake:

> cmake .

Then build the project. If you’re on Linux, just run “make” immediately afterward. On my Windows development machine, cmake generated an .sln file (and various project files) for Visual Studio, which I opened and built. The output was the executable MTConnect Agent.

It would be convenient if pre-compiled binaries were available for Windows. The README on GitHub suggests that they’re provided in a /bin directory, but that’s not present in the repository (and is probably excluded automatically by Git).

Step 3: Configure the MTConnect Agent

Now you have the MTConnect Agent executable, but you’ll need to configure it before you run it. There are two configuration files that you’ll probably need to modify.


The MTConnect Agent needs to know some basic information about how it should work. If you’re coming from the .NET world, you might expect it to look for an App.config file containing XML configuration data. Or if you have a Linux background, you might expect it to look for an agent.conf file containing sections and key-value pairs.

In what seems to be a fair compromise, the agent looks for neither of these. Instead, it looks for a file named agent.cfg, which is in something called “Boost C++ file format”. Whatever that is, it’s pretty straightforward. Let’s look at an agent.cfg that’s minimal but still instructive.

Devices = VMC-3Axis.xml





    Host =

    Port = 7878 # *Default* value...



This example is taken straight from the README.

The “Devices” line tells the agent to look for a file named “VMC-3Axis.xml” for device configuration. I’ll cover that momentarily.

The Adapters section is everything contained in the curly braces following “Adapters”. In this example, there is a single adapter definition, named “VMC-3Axis”. That name is just for your convenience: the adapter could be named “Adapter1”, “MyMachineAdapter”, or “Bob” with no change in meaning.

The definition for “VMC-3Axis” is everything contained in the curly braces following it. The specified Host is, and the specified Port is 7878 (the hash “#” is a comment). This tells the MTConnect Agent where the Adapter should be located.

You can specify zero or more adapters within the “Adapters” section. If you specify none, the MTConnect Agent will attempt to connect to localhost on port 7878. See the README for the MTConnect Agent for a full list of supported configuration items for an adapter.

The MTConnect Agent README also lists additional configuration options for the Agent itself. For example, if you want the Agent to run on on a port other than the default port 5000, you can specify that with a Port line.


Next, the MTConnect Agent needs to know about the data it should serve. By default, it will look for a Devices.xml file, whose format is exactly the format of an MTConnectDevices document that it would serve in response to a probe request.

Here’s another example taken from the /sample folder of the MTConnect Agent code. (I’ve stripped out a few bits for brevity.)

<?xml version="1.0" encoding="UTF-8"?>

<MTConnectDevices xmlns:m="" xmlns:xsi="" xmlns="">

  <Header creationTime="2009-03-22T01:50:29+00:00" sender="localhost" instanceId="1237628993" bufferSize="100000" version="1.1"/>


    <Device uuid="000" name="LinuxCNC" sampleInterval="10.0" id="d">

      <Description manufacturer="NIST" serialNumber=""/>


        <Controller name="Controller" id="cont">


	    <Path name="path" id="path">


		<DataItem type="BLOCK" category="EVENT" id="p1" name="block"/>

		<DataItem type="CONTROLLER_MODE" category="EVENT" id="p2" name="mode"/>

		<DataItem type="LINE" category="EVENT" id="p3" name="line"/>

		<DataItem type="PROGRAM" category="EVENT" id="p4" name="program"/>









I won’t go into detail here about how to create the file, but the key point is to make sure that the data served up by your Adapter is hooked up to a DataItem tag somewhere. The Adapter will output data in a form that might look something like this:


The MTConnect Agent will interpret that as meaning that some item with a key of “mode” has a new value of “AUTOMATIC”, as of the given timestamp. The Agent will then try to map “mode” to one of the DataItem tags specified in Devices.xml, by matching it up with a DataItem whose Source, name, or id matches the key. In this case, it will find the following DataItem:

<DataItem type="CONTROLLER_MODE" category="EVENT" id="p2" name="mode"/>

Cross your fingers

And there you have it. Your MTConnect Agent is built. Your agent.cfg and Devices.xml configuration files are ready. Now just run the MTConnect Agent. If all is well, you should now be able to load http://localhost:5000/current/ (or run your chosen MTConnect client application) and see data from your machine tool, served by the MTConnect Agent. Good luck!

If anything that I said was unclear, glossed-over, incomplete, or just flat-out wrong with a capital-R, please let me know. 🙂

15 thoughts on “Set up an MTConnect Agent in three or so steps

  1. The MTConnect agent will not run without a configuration file (agent.cfg). If run from the command line, it will print a help message and immediately close. You are likely not getting a response on port 5000 because the agent is not running.

    Port 7878 is the default port for an MTConnect adapter. This is a separate component from the agent, and from your description, it sounds like the adapter is running.

    Try to locate the missing agent.cfg file — if both Mazak machines are identical, you might be able to use the other for reference.

  2. I am new to plc world

    I would like to know why:


    machine 1

    have version mtconnect

    folder have agent.cfg

    port 5000 return well xml

    port 7878 returns well data


    machine 2


    folder have adapter.cfg but not agent.cfg

    port 500 NOT return xml

    port 7878 return data well


    please any advice about of this. the machines are Mazak same model

    sorry my English is nad

    thanks in advance

  3. hi , I am new to PLC world and I like learn anything I saw a problem with one friend when check mtconnect
    1 machine have this version mtconnect
    folder have agent.cfg
    Port 5000 returns well-formed XML. Port 7878 returns data
    2 machine have this version mtconnect
    folder have adapter.cfg not agent.cfg
    Port 5000 NOT returns well-formed XML. Port 7878 returns data
    what he should do so machine to return data port 5000 if the folder doesn’t have agent.cfg
    thanks in advance
    sorry my English is bad

  4. tying to follow your instructions, but I get this error:

    The C compiler identification is MSVC 19.10.25017.0
    The CXX compiler identification is MSVC 19.10.25017.0
    Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.10.25017/bin/HostX86/x64/cl.exe
    Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.10.25017/bin/HostX86/x64/cl.exe — works
    Detecting C compiler ABI info
    Detecting C compiler ABI info – done
    Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.10.25017/bin/HostX86/x64/cl.exe
    Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2017/Community/VC/Tools/MSVC/14.10.25017/bin/HostX86/x64/cl.exe — works
    Detecting CXX compiler ABI info
    Detecting CXX compiler ABI info – done
    Detecting CXX compile features
    Detecting CXX compile features – done
    You have called ADD_LIBRARY for library cppunit without any source files. This typically indicates a problem with your CMakeLists.txt file
    Configuring done
    CMake Error at libxml2_make/CMakeLists.txt:58 (add_library):
    Cannot find source file:


    Tried extensions .c .C .c++ .cc .cpp .cxx .m .M .mm .h .hh .h++ .hm .hpp
    .hxx .in .txx

    CMake Error: CMake can not determine linker language for target: libxml2
    CMake Error: CMake can not determine linker language for target: cppunit
    Generating done

    Any help would be greatly appreciated!

  5. Hi,
    I want to connect HEIDENHAIN Cnc machine with the help of Mtconnect.. I have successfully connected some FANUC m/cs already, but i am not sure about HEIDENHAIN.. Are the mtconnect adapters and agent available for this too. Please Help.

  6. I haven’t had the opportunity to work with the agent in awhile. The file format is a little unusual, but based on example 3 in the readme file, the comma shouldn’t be necessary.

  7. I was wondering about adding multiple adapters in the agent.cfg. Do you just comma separate them like this?

    Host =
    Port = 7878 # *Default* value…
    Host =
    Port = 7878 # *Default* value…

  8. Great! I guess I am much clear on what I have to do. Thank you so much! I may again disturb you in case of any issue! 😛

    Thank you so much.
    Mayur Shah

  9. As long as you have some way of connecting to the PLC, it should be possible to get data out of it.

    If you’re connecting through modbus, the MTConnect adapter project contains a modbus adapter. It’s accessible at I haven’t used that adapter, so you’ll want to contact the original author of it for usage instructions.

    For other connection methods, I would need to know more about your project. Worst-case, someone might have to develop an adapter suitable for your device.

  10. Its that possible for me to communicate with PLC and collect even data using MTConnect?

    If its possible how?

    I am new to PLC world and your direction will really help me!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s