Connect an AI assistant

This page connects an AI assistant that supports MCP to your Hermetry organisation. What the assistant can then do is explained in AI assistants (MCP).

Before you start

• An administrator has switched on Settings > MCP > Let MCP clients connect. While it is off, every MCP call answers 403 “MCP is switched off for this workspace (Settings → MCP)”.
• You hold Connect MCP clients (mcp_server.connect). Every built-in role has it.
• You hold the permissions of the tools you want: View devices for the device tools, and the telemetry read permission for the telemetry tools.

Your server addresses

Each module has its own MCP server. Its address is your workspace’s address followed by /api/mcp/<server>:

Server	Address
Devices	https://<your host>/tenant/<tenantId>/api/mcp/iot_device
Telemetry	https://<your host>/tenant/<tenantId>/api/mcp/telemetry

If your organisation has its own web address (for example https://acme.<your host>), the address is https://acme.<your host>/api/mcp/iot_device. Use the form that matches the address you see in your browser.

Add both servers to your assistant: the telemetry tools need the device ids that list_devices returns.

To see every server and tool you can use, call the index with an API key that holds Connect MCP clients:

curl -s "https://<your host>/tenant/<tenantId>/api/mcp" -H "Authorization: Bearer sk_live_…"

{
  "enabled": true,
  "servers": [
    { "server": "iot_device", "path": "/api/mcp/iot_device", "tools": [
      { "name": "get_device", "title": "Get a device", "kind": "read" },
      { "name": "list_devices", "title": "List devices", "kind": "read" } ] },
    { "server": "telemetry", "path": "/api/mcp/telemetry", "tools": [
      { "name": "get_latest_readings", "title": "Get latest readings", "kind": "read" },
      { "name": "get_reading_series", "title": "Get a reading series", "kind": "read" } ] }
  ]
}

Option 1: connect with an API key

Use this for assistants that run on your computer or your own server and let you set an HTTP header.

1. Open API Keys > New API Key.
2. Name it after the assistant and the person, for example “Desktop assistant – Alex”.
3. Under Module permissions, tick Connect MCP clients (group MCP), and the Read only preset of the devices module and of telemetry.
4. Set a short expiry and, if the assistant always runs from one network, an IP allowlist.
5. Create the key and copy it.
6. In the assistant’s MCP settings, add a server of type HTTP (sometimes called “Streamable HTTP”) with the address above and the header:

Authorization: Bearer sk_live_…

1. Repeat for the second server, with the same key.

Many assistants take a JSON configuration like this (the exact file and field names depend on the assistant):

{
  "mcpServers": {
    "hermetry-devices": {
      "type": "http",
      "url": "https://<your host>/tenant/<tenantId>/api/mcp/iot_device",
      "headers": { "Authorization": "Bearer sk_live_…" }
    },
    "hermetry-telemetry": {
      "type": "http",
      "url": "https://<your host>/tenant/<tenantId>/api/mcp/telemetry",
      "headers": { "Authorization": "Bearer sk_live_…" }
    }
  }
}

The names on the left are your own labels. The key acts as you, limited to what you ticked. See MCP keys and connected apps.

Option 2: connect with a sign-in (OAuth)

Use this for assistants hosted on the web that let you add a “custom connector” or “remote MCP server” by address.

1. In the assistant, add a connector with the server address, for example https://<your host>/tenant/<tenantId>/api/mcp/iot_device. Leave any client id and secret fields empty.
2. The assistant opens a Hermetry page. Sign in if asked.
3. Hermetry shows Connect to this workspace? with “Its identity is published at .” and “It acts as you, and never with more than your access in this workspace.” For a read-only connection it adds “It can read what you can read through the workspace’s AI tools. It cannot change anything.”
4. Check the app name and host, then select Connect. Cancel sends the assistant away without access.
5. Repeat for the telemetry server. Each server is added on its own, with its own address.

The app appears in Connected apps. “You can disconnect it at any time in Connected apps.”

If Hermetry shows This app cannot connect, the app’s host is not one Hermetry knows. Hermetry accepts a built-in list of well-known AI apps; an administrator can add more hosts under Settings > MCP > More AI apps. See MCP settings and safety.

What happens during the sign-in

For the people who run the assistant side:

• The server answers an unauthenticated call with 401 and WWW-Authenticate: Bearer resource_metadata="<base>/api/mcp/oauth/protected-resource/<server>".
• Authorisation server metadata is at <base>/api/mcp/oauth/.well-known/oauth-authorization-server (also openid-configuration).
• Clients identify themselves with a client id that is the https address of a client metadata document; there is no dynamic client registration.
• Only the authorisation code flow with PKCE (S256) is accepted, with an exact redirect address (https, or http on the local machine for desktop apps) and a resource that is this workspace’s MCP base or one server.
• Scopes: mcp:read; mcp:write is granted only within 15 minutes of a fresh sign-in (“Sign out and sign in again, then connect the app: letting it change records needs a fresh sign-in.”). The IoT tools need only mcp:read.
• Access tokens last 10 minutes. Refresh tokens are replaced on every use; reusing an old one revokes the connection. A connection lasts at most 90 days.
• Tokens can be revoked at <base>/api/mcp/oauth/revoke.

Check that it works

Ask the assistant “List my devices”. It should call list_devices and answer with names from your organisation.

Symptom	Cause
401	Wrong or expired key, or a key of another organisation; or the app was disconnected
403 “MCP is switched off for this workspace”	An administrator must switch MCP on
404	The server name is wrong, or its module is not on for your organisation
No tools listed	The key or you lack the tools’ permissions, or the tools are switched off
405	The assistant used GET; it must use POST (Streamable HTTP, JSON answers)
A cookie-based session is refused	MCP accepts only a key or a token in the Authorization header
403 from a web page	Calls carrying a browser Origin of another site are refused
415	The request was not sent as application/json

Technical notes

• Transport: Streamable HTTP, POST only, JSON answers, no sessions (no Mcp-Session-Id). GET and DELETE answer 405.
• Protocol revision 2025-11-25; newer revisions are answered too.
• Request bodies up to 64 KiB; Content-Type: application/json.
• Each server reports a technical name that your assistant may show. Clear names that start with hermetry-, which you can change for your organisation, are in development.