CDRouter MCP Server

CDRouter includes an MCP server that gives your AI agent access to your CDRouter system. Instead of copying logs into a chat window, you can ask your AI “why did my last result fail?” and it looks up the result, reads the test log, and answers from what it finds.

CDRouter does not include an AI of its own. There is no model and no chat window in CDRouter. You bring the AI and the AI agreement you already have, and the MCP server is another way in, like the API, working on the same configs and results you see in the CDRouter web interface. The MCP server is included with CDRouter 16.11 at no added cost and is off by default.

What You Can Do

With your AI connected, you can:

  • Find out why a test failed. Your AI reads the log, the test case, the testvars and earlier runs, then explains the failure in terms you can hand to the developers who will fix it. If your AI is also connected to your ticketing system, it can file the bug for you.
  • Build a config from your device. Describe what your device supports, and your AI builds a config and package from CDRouter’s own testvar definitions, so you can start without learning every testvar first.
  • Fix and rerun. Your AI can change a config, start the job, and read the new result.

To see what to ask, see Example Prompts for the CDRouter MCP Server.

What Is MCP?

MCP, the Model Context Protocol, is an open standard that lets an AI use tools provided by other software. The CDRouter MCP server provides tools for looking at your results, logs, configs and devices, and for running tests. You do not need to name them. Your AI decides which tools to use to answer your question.

Your AI has the same access as the user whose API token you give it. It works just like the API. For more about users and what they can see, see The CDRouter User Model.

What your AI reads goes to wherever its model runs. Test logs, configs and device details can contain IP addresses, hostnames and other sensitive information. If you already trust your model provider with this data, the MCP server works as is. If not, use a local model.

Before You Begin

You need:

  • CDRouter 16.11 or later.
  • An admin CDRouter account. Only admins can turn the MCP server on or off.
  • Automatic login turned off. The MCP server identifies who is asking by their API token, and automatic login ignores API tokens, so the two cannot be used together.
  • An AI that can connect to a remote MCP server over HTTP with a custom header. See Connect Your AI for the settings for Claude, Codex, GitHub Copilot and other AI clients.
  • A computer that can reach your CDRouter system on the network. Your AI connects from your computer to CDRouter.

Enable the MCP Server

  1. If automatic login is on, turn it off. Go to System > Automatic Login and click Disable Automatic Login. You are logged out, and you then log in with a username and password.
  2. Point to your username in the top right corner and choose MCP server.
  3. Click Enable MCP server and confirm.

The page now shows the MCP server address and a Connect an AI Assistant section with a tab for each AI client. The commands on those tabs already contain your own API token, so you can copy them as they are.

If you turn automatic login back on, the MCP server is switched off. Turn automatic login off and enable the MCP server again to use it.

Connect Your AI

This section has the settings for Claude, Codex, GitHub Copilot and other AI clients.

The commands below use http://lab1/api/v1/mcp/ as the CDRouter address and YOUR_API_TOKEN as the token. Use the commands on the CDRouter MCP server page, because they are already filled in with your address and token.

The server name in each command is cdrouter- followed by the hostname of your CDRouter system. For lab1 the name is cdrouter-lab1. Because every system gets its own name, you can connect the same AI client to more than one CDRouter system. See Connect More Than One CDRouter System.

You can find your API token on your user page in CDRouter. Treat it like a password: anyone who has it can act as you.

Claude

Claude Code

Run this in a terminal:

claude mcp add --transport http cdrouter-lab1 http://lab1/api/v1/mcp/ \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Claude Desktop

Claude Desktop only starts programs on your own computer, so it connects through a small helper called mcp-remote. This requires Node.js to be installed.

Add this to the "mcpServers" section of your Claude Desktop configuration, then quit and reopen Claude Desktop:

"cdrouter-lab1": {
  "command": "npx",
  "args": ["mcp-remote", "http://lab1/api/v1/mcp/",
           "--header", "Authorization:${AUTH_HEADER}",
           "--transport", "http-only", "--allow-http"],
  "env": { "AUTH_HEADER": "Bearer YOUR_API_TOKEN" }
}

Codex

Set the token in the terminal where you start Codex. The variable name is CDROUTER_TOKEN_ followed by the hostname of your CDRouter system in capital letters, with dashes replaced by underscores:

export CDROUTER_TOKEN_LAB1=YOUR_API_TOKEN

Then add this to your Codex configuration. The server name cannot contain dots, which is why the name uses dashes:

[mcp_servers.cdrouter-lab1]
url = "http://lab1/api/v1/mcp/"
bearer_token_env_var = "CDROUTER_TOKEN_LAB1"

GitHub Copilot

Run this in a terminal:

copilot mcp add --transport http --header "Authorization: Bearer YOUR_API_TOKEN" \
  cdrouter-lab1 http://lab1/api/v1/mcp/

Other AI Clients

Any AI client that supports a remote MCP server of type “streamable HTTP” can connect. Add a server with:

  • URL: http://lab1/api/v1/mcp/
  • Header: Authorization: Bearer YOUR_API_TOKEN

Connect More Than One CDRouter System

The MCP server runs on each CDRouter system, so you need to configure your AI client for each system you want it to use. Repeat the connection steps for each system, using the commands from that system’s MCP server page. Each system has its own API token, and each connection has its own name, such as cdrouter-lab1 and cdrouter-lab2, so they do not replace each other.

When your AI can use more than one system, specify which one you mean:

On lab2, list my five most recent results.

Your AI acts as the user whose token you gave it on each system, so it can see different things on each one.

Verify That It Works

Ask your AI:

Which CDRouter user am I connected as?

It should answer with your CDRouter username and whether you are an administrator. Then try:

List my five most recent results.

If your AI does not seem to know about CDRouter, restart it. AI clients read the list of available tools when they connect, and most do not notice changes until they reconnect.

Permissions and Privacy

  • It works just like the API. Users connect with their existing API token and get the same access. As with the API, a token is all or nothing: it gives your AI the same access as the user it belongs to. If that user is not an administrator, your AI can work only with the items that user can see.
  • Your AI can create and update configs, packages and devices, start and stop jobs, and add notes to log lines. It cannot delete anything. Changes are marked so that your AI client can ask you first.
  • Some actions need an administrator: starting tests, listing queued jobs, viewing system information, and creating configs, packages and devices.
  • A device’s password and its power commands are never shown to your AI and cannot be set through it.
  • Each request is recorded in the CDRouter log with the user, the tool and the outcome. The details of the request are not recorded. Changes your AI makes also appear on the History page, marked as made through the MCP server.

What It Cannot Do

  • It does not analyze metric values. Your AI can see which metrics were recorded, but not their values.
  • CDRouter does not analyze results or make decisions on its own. Your AI does the analysis. CDRouter provides the data and carries out the changes you ask for.

Troubleshooting

What you see What to do
The MCP server page says it is unavailable Automatic login is on. Disable it under System > Automatic Login.
401 or invalid token The token is wrong. Copy the current token from your user page.
503, “the MCP endpoint is not enabled” An administrator has not enabled the MCP server.
403, “unavailable while automatic login is enabled” Disable automatic login.
An error about Unexpected token '<' The token was rejected. Check it, then reconnect.
New tools do not appear after an upgrade Restart your AI client so it reads the tool list again.
Your AI says it cannot do something It may need an administrator account. See Permissions and Privacy.

See Also