Skip to content

Connect an AI Agent to a Safe

Overview

This guide explains how to connect an AI agent to an existing UnoLock Safe using an Agent Key and the UnoLock MCP.

This workflow is for customers who want an AI assistant or automation host to read Safe content without giving it unrestricted Safe access.

Before You Start

Make sure you have:

  • an existing UnoLock Safe
  • admin access to that Safe
  • a host environment where you can run the UnoLock MCP
  • the UnoLock Agent MCP installed from the official GitHub repository:
  • https://github.com/TechSologic/unolock-agent-mcp

If possible, use a host with:

  • TPM
  • vTPM
  • or a platform-backed secure key store

Install the UnoLock Agent MCP

Install the official UnoLock Agent MCP from:

  • https://github.com/TechSologic/unolock-agent-mcp

Follow the install instructions in that repository for your MCP host and operating system before continuing.

Create the Agent Key

  1. Open your Safe in UnoLock.
  2. Go to Configuration.
  3. Open the access key management screen.
  4. Create a new key.
  5. Choose Agent Key.
  6. Give the key a name.
  7. Choose its permission level:
  8. ro
  9. rw
  10. admin
  11. If needed, restrict the key to selected Spaces.
  12. Decide whether it should use the same PIN behavior as your current access or a different PIN.
  13. Finish the key-creation flow.

At the end, UnoLock will generate a one-time agent key connection URL.

Give the URL to the Agent Host

  1. Start the UnoLock MCP on the host where the AI agent will run.
  2. Let the AI agent inspect MCP registration status.
  3. When it asks for a UnoLock agent key connection URL, provide the generated URL.

The expected format is an agent URL such as:

#/agent-register/...

Do not give the agent a normal browser access-key URL such as #/register/....

If the agent host starts cold and knows nothing about UnoLock yet, that is expected. The MCP should tell the agent to ask you for the UnoLock agent key connection URL first, and then ask for the PIN only if the key requires one.

Complete Registration

  1. The MCP uses the one-time connection URL to begin registration.
  2. If the key requires a PIN, the AI agent will ask you for it.
  3. Provide the PIN.
  4. The MCP finishes registration and stores the new agent credential on that host.

After successful registration:

  • the one-time connection URL cannot be reused
  • the MCP remains registered to that Safe
  • the PIN is kept only in process memory

Use the Agent

Once registered and authenticated, the agent can use the MCP to:

  • list visible Spaces
  • list notes
  • list checklists
  • retrieve records in an agent-friendly format

The agent will only see what the Agent Key is allowed to see.

What Happens After Restart

If the MCP or host restarts:

  • the agent remains registered
  • the local session is gone
  • the agent must re-authenticate
  • if the key uses a PIN, the agent asks you for the PIN again

This is expected behavior.

Disconnect the Agent

If you want to remove the local MCP registration from a host:

  1. Run the MCP disconnect command or tool.
  2. Delete or rotate the agent key in UnoLock if you want full revocation.

Disconnecting locally removes the local host credentials, but it does not automatically delete the server-side access record.

Troubleshooting

The MCP says it needs a connection URL

Give it the agent key connection URL generated from an UnoLock Agent Key.

The MCP says the URL is the wrong type

You probably provided a normal access-key registration URL instead of an agent key URL.

The MCP asks for the PIN after restart

That is expected. The agent stays registered, but the PIN is not persisted in process memory.

The MCP says TPM or vTPM is not production-ready

Run the MCP TPM diagnostics and follow its advice. Some hosts support stronger device binding than others.