Skip to main content

Connect an AI assistant

By the end of this page you will have an AI assistant connected to your account, you will have checked that it works, and you will know how to cut it off again.

It takes about two minutes. You do not copy any password or token — you sign in through your browser and approve the client by name.

MCP may not be available on your platform

Open MCP from the user menu at the top right, or the MCP Connections tile on the home page. If the page says MCP is not enabled on this deployment, or you do not see it at all, your platform has not switched it on. Ask your administrator.

Before you start​

  • An AI client that supports MCP. The Setup tab has instructions for Claude Code, Claude Desktop, Codex, Gemini CLI, Antigravity, Cursor and VS Code.
  • Know what your plan allows. A Free account's assistant can read everything and manage devices and SSH keys; deploying and working inside labs needs Pro. See What your plan allows.

It acts as you — nothing more​

A connected assistant has your permissions, and only yours. It reaches the labs, domains, devices and services you can reach, and it is refused what you are refused. It never sees your password.

That also means it can do anything you can — including stopping a lab or deleting a file. Treat a connected client the way you would treat someone at your keyboard.

1. Open the Setup tab​

Open MCP from the user menu. The Setup tab walks you through the connection for the client you pick.

The client picker with one client selected, the '1 · Add the server' box with its copy button, the '2 · Sign in' step, and the side card showing the server address and Connected clients.

2. Pick your client​

Choose it under Your client. The steps below it change to match.

3. Add the server​

Step 1 · Add the server shows exactly what to run or paste, with a copy button. It already contains your platform's server address.

ClientWhere it goes
Claude CodeA command you run in your terminal, shaped like claude mcp add --transport http labs <server-address>
Claude DesktopSettings → Connectors → Add custom connector, then paste the address
Codex, Gemini CLI, VS CodeA command you run in your terminal
Cursor, AntigravityA few lines added to the client's MCP settings file
Using ChatGPT or Claude in the browser?

Step-by-step instructions for adding Labs as a ChatGPT app or a Claude connector are in Connect ChatGPT or Claude.

Copy the address from the Setup tab, not from anywhere else

The address is specific to your platform, and it must be exactly what the Setup tab shows. A client pointed at a slightly different address reports session not found or failed to connect.

4. Sign in and approve​

Step 2 · Sign in tells you how to start sign-in from your client. In Claude Code, for example, type /mcp, choose labs, then choose Authenticate.

A browser window opens, signs you in with the account you already use for the platform, and asks you to approve the client by name.

Approve only clients you started yourself

If an approval screen appears that you did not trigger just now, deny it. An approved client can act as you.

5. Check it works​

The client appears under Connected clients on the Setup tab as soon as it signs in. Then ask it something harmless:

"Who am I on Selfmade Ninja Labs, and what can you do for me?"

The assistant calls whoami, which confirms the connection end to end and reports your account, your plan, the tool tier you have and the organizations you can act for. Then try:

"List my labs."

It calls list_labs. If you get your labs back, you are done.

The answer to 'List my labs' — the client showing the list_labs call and a short list of labs with their status.

If it does not connect​

What you seeWhat to do
session not found, failed to connect, or a 404The address is wrong. Copy it again from the Setup tab.
Unauthorized or 401The client has not signed in, or its sign-in expired. Run the sign-in step again.
Tools appear but everything you ask is refused as "not available"Your plan does not include that tool. See What your plan allows.
The approval page never opensYour client may need you to start sign-in by hand — follow step 2 · Sign in for your client.

What to ask first​

The assistant knows how to find its way around — it reads the platform's own guide and picks tools itself. You do not need to name tools. A few good first requests:

  • "What labs do I have, and which are running?"
  • "Give me the SSH command for my Essentials lab."
  • "Is the certificate on my site OK?"
  • "I want to build a small notes app. Where do I start?"

For everything else, see What you can ask and the worked examples.

Tell the assistant about your lab​

An assistant does better work when it knows your lab's conventions — where the code lives, how to restart the app, what not to touch.

  • Per lab: open the lab → Preferences → Agent Prompt. Write your instructions (up to 64 KB) and click Save Agent Prompt. This section only appears when MCP is enabled.
  • From the template: if the Agent Prompt is empty, the assistant gets the template's PROMPT.md instead. Template authors write it — see Auto-login and connection info.

See what it did​

The Activity tab on the MCP page lists every call each client made in the last 30 days, with the request, the response, whether it worked and how long it took. Only you can read it. Details in History and safety.

Disconnect a client​

  1. Open Account Settings → Security.
  2. Under MCP clients, find the client. Live means it used your account within the last few minutes; Idle clients still hold a working sign-in.
  3. Click Disconnect.

The client must sign in and be approved again before it can do anything else. The Manage in Account security link on the MCP page takes you to the same list.

The MCP clients list with at least one Live and one Idle client, each with its Disconnect button.

Next​

Last updated on