Skip to main content

Connect your AI assistant to Azumuta

BETA: Azumuta MCP is currently in beta and may still evolve. It is available by opt-in only. To join the beta or ask questions, contact support@azumuta.com.

Model Context Protocol (MCP) connects your preferred AI assistant to permitted Azumuta data. You can ask questions about work instructions, product orders, recordings, and issues without manually copying that data into a conversation.

The Azumuta MCP tools are read-only. They cannot change your workspace. See Use Azumuta MCP for examples and limitations.

Before you start

  • Enable the MCP beta for your workspace.
  • Use an AI assistant approved by your organization. The assistant must support remote MCP connections and an Authorization header.
  • Make sure you have permission to manage API devices, or ask your workspace admin to create the key.
  • Review which data you may share with the AI client and its model provider. Retrieved data goes to that client and provider.

Cursor is the illustrated example in this guide. Other AI assistants have different setup controls. You do not need to install the Azumuta MCP server on your computer.

If API scopes is not available, or for assistance with connection setup, contact support@azumuta.com.

Create a key with read access

An API key selects the workspace and controls which data categories the assistant can access. Its access does not necessarily match your web-app permissions. Ask your admin to review it before connecting.

  1. Create a dedicated API device in the workspace you want to connect.
  2. Open Edit device for that device.
  3. Open Security.
  4. Under API scopes, select Restrict this API key to a subset of operations.
  5. Clear the selected scopes that you do not need. The initial selection includes all scopes.
  6. Select only the required Read options from the table below.
  7. Save the device.
  8. Copy its API key.
Scope group Read access Scope identifier
Work instructions Work instructions, content, and versions workinstructions:read
Recordings Work-instruction recordings and structured report data recordings:read
Products Product orders and their execution details products:read
Issues Issues, boards, flows, and status changes issues:read
Users User details users:read
Spots Zones and stations spots:read

MCP requires explicit scopes. A key without selected scopes does not provide unrestricted MCP access. Some questions need several scopes, such as Work instructions and Recordings.

API scopes filtered to Work instructions, with Read selected and Write and Delete cleared

Connect your preferred AI assistant

For a workspace on app.azumuta.com, use these settings:

Setting Value
Connection type Remote MCP using Streamable HTTP
Server URL https://mcp.azumuta.com/mcp
Header name Authorization
Header value Bearer <AZUMUTA_API_KEY>

Replace <AZUMUTA_API_KEY> with your key. Keep the space after Bearer. This connection uses an API key, not an Azumuta browser sign-in.

Use a key from the matching environment. A sandbox key does not connect to production. For another environment, use its confirmed MCP endpoint.

Example: connect in Cursor

  1. Open Cursor Settings.
  2. Open Customize.
  3. Select MCPs.
  4. Select New MCP Server. Cursor opens the user-level mcp.json configuration file.
  5. Add the azumuta entry below inside mcpServers. Keep any existing server entries.
  6. Replace <AZUMUTA_API_KEY> with your dedicated key.
  7. Save the file.
  8. Return to Customize → MCPs.
  9. Open the Azumuta server settings.
  10. If the connection is disabled, enable it.
  11. Check that the connection shows Connected and lists the expected tools.
{
  "mcpServers": {
    "azumuta": {
      "url": "https://mcp.azumuta.com/mcp",
      "headers": {
        "Authorization": "Bearer <AZUMUTA_API_KEY>"
      }
    }
  }
}

The user-level file is ~/.cursor/mcp.json. It can make this connection available across your projects. Do not put a real key in a shared project configuration, repository, prompt, or screenshot. Cursor also supports environment-variable references in header values; see Cursor's MCP documentation.

Cursor shows the Azumuta connection as Connected and lists read tools

Verify the connection

In the illustrated Cursor version, Agent mode permits these MCP calls. Ask mode can block them. Limit the request to Azumuta MCP and review the tools used. Other Agent tools can have write access.

  1. Start a new conversation with your AI assistant.
  2. Enter: Use Azumuta MCP to list five work instructions. Include their names and IDs.
  3. If the client requests approval, review the tool and its arguments before approving the read.
  4. Compare the returned work instructions with the selected Azumuta workspace.

This check requires Work instructions: Read. An empty list does not by itself mean the connection failed. Check the tool response and whether the workspace contains accessible work instructions.

Continue with example questions and limitations.

Connection problems

Symptom Check
Authentication error Confirm the endpoint, matching environment, API key, and Bearer header. Never include the key in a support message.
Access denied or no expected tools Confirm beta access and the key's explicit Read scopes. After changing scopes, reconnect or refresh the tool list.
A record cannot be found Check its name or ID and the workspace selected by the key.
The response is too large or incomplete Narrow the question. Specify a record, filter, or small number of results. Ask whether more pages remain.

Disconnect or revoke access

To stop using the connection in one client, disable or remove the Azumuta MCP entry there. This does not invalidate the API key.

To revoke the key:

  1. Go to Management → Devices → API in Azumuta.
  2. Open the row menu for the dedicated API device.
  3. Select Delete device.
  4. Confirm the deletion.

Deleting the device invalidates its key for all integrations that use it. Check that the device is not shared before deleting it. Revocation does not remove data already returned to an AI conversation.