i-doit MCP#

The i-doit MCP add-on connects your IT documentation to AI clients that support the Model Context Protocol (MCP). An AI assistant can then answer questions about your CMDB in ordinary language, for example "Which servers do we have in Hamburg?" or "Where is LAPTOP-42 located?".

The assistant always works with the permissions of the person its access token belongs to. It never sees or changes more than this person could in i-doit itself. Out of the box, access is read only. Writing has to be switched on explicitly, see Write access.

Requirements#

1
2
3

<FilesMatch "^(jsonrpc\.php|mcp\.php)$">
    Require all granted
</FilesMatch>

1
2
3

RewriteEngine On
RewriteCond %{HTTP:Authorization} .+
RewriteRule ^ - [E=HTTP_AUTHORIZATION:%0]

Installation#

The add-on is installed like every other add-on, see Add-ons. After the installation, you find it in the main menu under Add-ons → i-doit MCP with three pages:

• How to connect
• Access tokens
• Request log

Assigning rights#

Under Administration → User permissions → i-doit MCP, permissions for persons and person groups can be adjusted:

Holding an access token is what admits a client to the MCP server. There is no separate permission for it. To withdraw access, disable or delete the token.

Connecting an AI client#

Open Add-ons → i-doit MCP → How to connect. The page shows the section Connect your AI assistant in 3 steps, a Setup status and the Client configuration.

The Setup status shows four items:

• i-doit API add-on: whether the API add-on is installed and loaded. Without it, category data cannot be read.
• JSON-RPC API switched on: whether the JSON-RPC API is switched on for the tenant. While it is off, every tool call is refused.
• Per-person permissions: a client always reads as the person its token belongs to. Nothing has to be configured for this.
• Write access: whether AI clients may change data, see Write access. This is not a prerequisite, reading works either way.

Only when the first two items are met can tool calls read data.

1. Get an access token#

Create a token on the Access tokens page with New:

1. Select the Person object the token belongs to. Only person objects can be selected.
2. Optionally enter a Label, for example the device or client the token is used on.
3. Save.

The new token is shown only once. Copy it right away. i-doit only stores a fingerprint, so the token cannot be displayed again later. If you lose it, delete the token and create a new one.

A token always belongs to the tenant in which it was created and only works there. The person of a token cannot be changed afterwards. Create a new token for another person instead.

2. Generate the configuration#

Paste the token into the Client configuration section and click Generate configuration. You receive two blocks to copy:

• a configuration file for clients that are configured via a file
• a command line for clients that are configured on the command line

Both blocks already contain the address of your i-doit installation and your token. The token field is optional. If you leave it empty, the blocks contain a placeholder instead of the token.

The page does not store the token. The field is empty every time you open the page.

The configuration file has this shape:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "mcpServers": {
    "i-doit": {
      "type": "http",
      "url": "https://idoit.example.com/src/mcp.php",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "Content-Type": "application/json",
        "Accept": "application/json"
      }
    }
  }
}

The command line, here for Claude Code:

1
2
3
4

claude mcp add --transport http i-doit https://idoit.example.com/src/mcp.php \
  --header "Authorization: Bearer <your-token>" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

3. Paste it into your AI client#

Paste the configuration into your AI client. The client discovers the available functions by itself. There is no prompt field in i-doit: you ask your questions in your AI client.

Managing access tokens#

The Access tokens page lists all tokens of the tenant. Select one or more tokens and use the buttons in the toolbar:

• Enable and Disable switch a token on or off. A client with a disabled token stops working immediately.
• Purge removes a token for good. This cannot be undone.
• Allow writing and Make read-only set whether a token may change data. The column Access shows read only or read and write.

New tokens are always read only.

Write access#

Reading works without any further setting. Writing needs all of the following at the same time:

1. The i-doit permission system is active: Permission system in the section Security of the tenant settings. It is active by default.
2. Allow write access through MCP is switched on under Administration → Add-ons → i-doit MCP. It is off by default.
3. The token is marked for writing (read and write).

In addition, every single change is checked against the CMDB permissions of the person the token belongs to, and it runs through the validation and the logbook of i-doit.

Purging data additionally needs Allow purge through MCP. This setting only takes effect while Allow write access through MCP is switched on as well.

Passwords are never returned to the AI client and cannot be written through MCP.

Settings#

The settings are located under Administration → Add-ons → i-doit MCP. Viewing and changing them requires the right for the system settings.

Request log#

The Request log page lists every request of the AI clients with time, person, method and tool. Show details opens the arguments and, if any, the error of a request.

• Export as CSV downloads the complete log. The filter on the page does not apply to the export.
• Clear the log deletes all entries. This cannot be undone.

Releases#