Skip to content

How to connect Profinity to AI tools like Claude or ChatGPT

Connect Profinity to AI tools and large language models (LLMs) using the Model Context Protocol (MCP) server integration. Three stages make the connection: enabling the MCP server, creating a service account token, and adding the server to the AI tool.

Profinity also has built-in AI

Profinity includes its own AI assistant, AI Chat, which answers questions about your live components, tags, and alerts without any external AI tool. To use it, an administrator only needs to enter an API key (token) from Claude, OpenAI, or OpenRouter, or the address of a local model, in Profinity AI settings. Connect an external AI tool when you want to use Profinity data from that tool instead.

Prerequisites

  • Profinity 2.3 installed and running
  • A licence that includes the AI feature, which the MCP server needs, and the Profinity Server feature, which Users & Groups needs for the service account. Both are included in the Server and Enterprise editions. On other editions the Enable MCP Server setting is unavailable. Refer to Licensing
  • Administrator access to the Profinity AI Settings and to user management
  • An AI tool or LLM client that supports MCP over Streamable HTTP with a custom Authorization header, because the Profinity MCP server authenticates every request with a JSON Web Token (JWT) bearer token
  • Familiarity with how your AI tool adds an MCP server

Enable the MCP server

  1. Select ADMIN in the side menu, then System Configuration.
  2. Find the Profinity AI category, and its MCP Server field group.
  3. Enable Enable MCP Server.
  4. Select Save.

Enabling or disabling the MCP server takes effect only after Profinity restarts, and Profinity shows a "Restarting, please wait..." message and refreshes the settings once the engine is running again.

The MCP server is then available at http://localhost:18080/api/v2/Ai/Mcp (using the default Profinity web server port). It uses Streamable HTTP transport, not Server-Sent Events (SSE), so there is no /sse path.

Create a service account and get a token

Every call to the MCP server requires a JWT bearer token for a user with the MCP integration permission. Each tool also checks its own permission before returning data: View tags for the tag tools and View alerts for the alert tools. A tag or alert the user cannot view is omitted from the response.

  1. Select ADMIN in the side menu, then Users & Groups, and select + Add user.
  2. Enter a name (for example "mcp-service"), and enable Service account.
  3. Assign a role that includes MCP integration, View tags and View alerts, and save the user.
  4. Select the user's row, open the User Actions tab and select Generate Token.
  5. Copy the token and store it in a secrets manager, because a service account token does not expire and stays valid until an administrator generates a new one or disables the account (refer to Service Accounts).

Get a token from the API

A script can instead authenticate with the service account username and password through the Profinity API, which puts the password on the command line:

curl -X POST http://localhost:18080/api/v2/Users/Authenticate \
  -H "Content-Type: application/json" \
  -d '{"username":"mcp-service","password":"your-password"}'

Configure your AI tool

A Profinity MCP client needs three things: the Streamable HTTP endpoint http://localhost:18080/api/v2/Ai/Mcp, the HTTP transport, and an Authorization: Bearer <token> header sent on every request. A tool on another machine replaces localhost with the address of the Profinity server, and the Profinity web server port must be reachable from that machine. Each AI tool enters these values in its own way, and the following example shows the common JSON form.

Examples that use Ollama are on the Prohelion GitHub page.

A client that reads an mcpServers JSON file with type, url and headers fields, the form used by tools such as Claude Code and Cursor, takes this entry, which is added to the AI tool's MCP server configuration with the name profinity:

{
  "mcpServers": {
    "profinity": {
      "type": "http",
      "url": "http://localhost:18080/api/v2/Ai/Mcp",
      "headers": {
        "Authorization": "Bearer YOUR_JWT_TOKEN_HERE"
      }
    }
  }
}

Replace YOUR_JWT_TOKEN_HERE with the token from the previous section and restart the AI tool.

Claude Code can add the same server from its command line:

claude mcp add --transport http profinity http://localhost:18080/api/v2/Ai/Mcp --header "Authorization: Bearer YOUR_JWT_TOKEN_HERE"

A client that cannot send a custom Authorization header, including a connector that supports only OAuth sign-in, cannot connect to the Profinity MCP server, because the server rejects an unauthenticated request.

Verify the connection

In the AI tool, ask "What components are in my active profile?", and a list of component names confirms the connection. Tag values and alerts are available in the same way.

What the AI tool can do

Once connected, the AI tool can use the ten read-only MCP tools to discover components and search the tag tree, read current tag values and tag history, and review active alerts and alert history. Refer to MCP Server for every tool and its parameters. The MCP server does not expose any tool that changes Profinity data, so changes such as generating dashboards or scripts are made in your AI tool and applied separately (refer to AI Skills).

Example questions to ask once the connection works:

  • "What components are in my active profile?"
  • "Show me the current battery voltage from the BMU"
  • "Which alerts have been raised in the last hour?"
  • "Plot the motor controller temperature over the last 24 hours"

Build Profinity content with AI Skills

The MCP server lets an AI tool read data from Profinity, while AI Skills lets an AI coding assistant such as Claude Code, Cursor, Codex, or ChatGPT build Profinity dashboards, rules, collections, scripts, plugins, derived tags, and example apps. AI Skills reads live data through the MCP server and the live schema through the Profinity REST API, and asks for approval before it saves any change to your instance. To add the skills to your AI tool, refer to Install AI Skills.

Troubleshooting

The connection fails

If the AI tool reports that the connection failed, the MCP server is disabled, Profinity has not finished restarting, the web server port is not reachable from the AI tool, or the endpoint path is wrong. Confirm that Enable MCP Server is on, that Profinity has restarted, and that the URL ends in /api/v2/Ai/Mcp, and check the Profinity logs for MCP connection issues. If the web server runs on another machine, make sure its port is allowed through the firewall.

Enable MCP Server is unavailable

The Enable MCP Server setting needs the AI licensed feature, so on an edition without it the setting cannot be used. Refer to Licensing.

No data is returned

If the AI tool connects but returns nothing, there may be no active components or profile, or the token's user lacks the View tags or View alerts permission. Make sure a profile with components is active and that the user's role includes the permission for the data requested.

Authentication errors

An authentication error means the token is incomplete, or its user lacks the MCP integration permission. Check that the token was copied completely and that the user's role includes MCP integration.

  • AI Chat: the built-in chat assistant, which uses the same MCP server
  • AI Skills: skills that let an AI coding assistant build Profinity dashboards, rules, and scripts
  • Install AI Skills: add the skills to your AI tool
  • Scripting: Profinity scripting
  • APIs: REST API documentation