Step 5: Connect an agent
An agent is any AI client that talks to your gateway over MCP: ChatGPT, Claude, Cursor, Claude Code, and so on. Connecting one gives it permission to use the integrations you have set up, governed entirely by your grants. The agent never receives your API keys: the gateway uses them on its behalf, and only for what you have allowed.
There is no "create the agent first" step. The agent proves who it is by connecting, and you approve it. Open Agents → Connect agent, or scroll to Connect an agent on the Settings → Gateway page.
The two values the dialog gives you
| What it is | When a client needs it | |
|---|---|---|
| MCP server URL | Your gateway's address | Always |
| Authorization header | A one-time setup code, valid 15 minutes | When the client cannot open a browser sign-in |
Pick your client from the dropdown below them and the dialog spells out where each one wants them: the exact menu, the exact file, or a command with your details already in it.
Which should I use?
What decides it is the client, not where the gateway runs.
Sign in, if the client can open a browser. Claude Desktop's Connectors, ChatGPT, claude.ai and Claude Code all can. Give the client the URL alone; it sends you to a Permaura sign-in, and approving on that screen is the approval, so the agent arrives already approved. Signing in needs a gateway with a public address: a hosted one always has one, and one on your own machine gets one from remote access.
The one-time code, for anything that can't. A script, a CI runner, a cron job, anything driven by curl, and any client that only reads a config file. It sends the code as its bearer token to the MCP server URL and arrives Pending on the Agents page for you to approve. That is as true of a hosted gateway as of one on your laptop: the gateway redeems a live code whichever way it is reached.
The Permaura iPhone app, on the App Store, offers both too. On the Agents screen, Connect an agent asks for an optional name, then shows the MCP server address to sign in against and, under Or a one-time code, a code for an agent that cannot.
Copy agent instructions puts the whole setup on your clipboard as a short prompt carrying the live URL and code. Paste it into any agent that can edit its own MCP config, and it connects itself.
About the code
It looks like pgc_ENRL-7F3A-9C21-4B8D-E0F1-A2B3-C4D5-E6F7-0819: eight groups after the prefix from gateway 1.3.56 (four from 1.3.22, two before that). A code from the console or the app starts pgc_ENRL- from gateway 1.3.46, and its agent counts as a remote caller wherever it connects from; on an older gateway the same code starts ENRL-. It is single-use and lives 15 minutes. The dialog counts it down beside the header, and Refresh mints a fresh one whenever you need it.
Once an agent redeems it, it stops being a shared secret and becomes that agent's own token. Keep sending the same value as the bearer; there is nothing to exchange it for. It keeps working while the agent is in use and stops after 30 days without a call, or the moment you remove the agent.
Naming it
The code carries a name, so an agent that connects with it is named from its first call: its row on the Agents page, the notice that it is waiting, and every approval it asks for. Type one in Agent name above the header, or leave it blank and the client you pick below fills it in (Claude Code, Cursor, and so on). A new name needs a new code, so set it before you copy. An agent connected with no name is named after what its client reports about itself (Claude Code reports "Claude Code") on gateway 1.4.6 and later, and shows up as "Enrolled agent" on an older one. You can rename any agent on the Agents page.
If your gateway has no public URL
Hosted clients like ChatGPT hand your URL to their vendor's servers, which cannot reach a gateway on your own machine. The dialog says so where you hit it and links straight to the setting. Turning on remote access gives the gateway a public URL over a secure tunnel while your keys stay put.
An agent on the same machine as the gateway needs none of that: it uses the loopback address, and the dialog offers it automatically.
Approving and removing agents
Every connected agent shows up on the Agents page. An agent waiting on you is not something you have to go looking for: the console bell counts it, and on a hosted gateway (1.3.24 and later) your phone is told too, the same way it hears about held approvals.
You can rename an agent, and you can remove one at any time. Removing it revokes its sessions immediately and deletes any grants that named only that agent, so a removed agent cannot quietly come back with access you thought you had taken away.
What an agent can actually do
Connecting an agent does not give it access to anything yet. Permaura is deny-by-default: an agent can only use a capability when a grant allows it. Approve the agent here, then give it the access it needs. That separation is the whole point: you approve who connects, and you decide what they can do.
For the exact steps in Claude Code, Claude Desktop, ChatGPT, Cursor and other clients, see Connect your AI client. If a client cannot see any tools, start with Troubleshooting.
➡️ Continue to Step 6: Grant access.