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've set up, governed entirely by your grants. Your API keys never leave the gateway, and the agent only ever gets to do what you've allowed.

There's no "create the agent first" step. The agent proves who it is by connecting, and you approve it. Open Agents → Connect agent and you'll see two ways to do it.

Two ways, easiest first

Remote (recommended)

Remote — point it at a URL, sign in, done

This is the easiest path and the one to reach for first. The agent connects to your gateway's public URL, you sign in to Permaura, and approving on that sign-in screen is the approval. There's no code to copy, and the agent shows up already approved.

It works with any MCP client that connects over the internet, including hosted ones like ChatGPT.

To use it, your gateway needs remote access turned on. That gives it a public URL over a secure tunnel while your keys stay on your machine. If it's off, the dialog tells you so and links you straight to the setting:

Turning it on takes a moment; the Remote access guide walks through it. Once it's on, come back to Connect agent and the Remote tab shows your URL.

Then, in your agent:

• Claude / Claude Code — run the one-line command the dialog shows:

  claude mcp add --transport http permaura https://g-xxxx.permaura.com/mcp

• ChatGPT, Cursor, others — paste the MCP server URL into their Connectors / MCP settings.

The first time the agent connects, it opens a Permaura sign-in. Approve it there, and it's connected — no code, no copy-paste of tokens.

Why this is safe

Signing in proves you authorised this agent, and the gateway only accepts agents authorised by its owner. The agent still can't do anything until your grants allow it: until then, every request is denied by default.

On this machine

Local — a one-time code for an agent on your computer

If the agent runs on the same machine as the gateway (for example Claude Desktop or Cursor on your laptop, talking to a local gateway), use the one-time code. No public URL or remote access needed.

The On this machine tab gives you a ready-to-paste MCP config:

Copy it into your agent's MCP config and restart the agent. (In Claude Desktop that's claude_desktop_config.json; Cursor and others have an equivalent.) The config points the agent at your local gateway and carries a short-lived enrolment code as its credential.

When the agent connects, it appears on the Agents page as Pending. Click Approve and it's live. The code is single-use and expires in 15 minutes; generate a fresh one with New code if it lapses.

Which should I use?

Use Remote for anything hosted (ChatGPT) or for an agent on a different machine, and whenever you want the no-code sign-in flow. Use Local for an agent on the same computer as the gateway when you'd rather not expose a public URL.

Approving and removing agents

Every connected agent shows up on the Agents page:

• A remote agent that signed in arrives already approved (your sign-in was the approval).
• A local agent arrives Pending until you click Approve.

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 can't quietly come back with access you thought you'd 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.

➡️ Continue to Step 6 — Grant access.