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 a password or token. You sign in through your browser and approve the client by name.
Open MCP from the user menu at the top right, or select 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.
A platform can also limit the MCP page to administrators. In that case the MCP link is missing for everyone else and opening the page directly shows Not Found.
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.
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.
| Client | Where it goes |
|---|---|
| Claude Code | A command you run in your terminal, shaped like claude mcp add --transport http labs <server-address> |
| Claude Desktop | Settings → Connectors → Add custom connector, then paste the address |
| Codex, Gemini CLI, VS Code | A command you run in your terminal |
| Cursor, Antigravity | A few lines added to the client's MCP settings file |
Step-by-step instructions for adding Labs as a ChatGPT app or a Claude connector are in Connect ChatGPT or Claude.
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.
labs.selfmade.ninja is the Selfmade Ninja Academy's own platform, used here as the example. If your school or company runs its own copy of Selfmade Ninja Labs, use your platform's domain instead, for example https://labs.your-college.edu/mcp. It is the address you open the dashboard at.
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.
The approval screen is headed Approve access and shows:
| Part | What to check |
|---|---|
| Client name is asking to use your labs | The name of the client you just started |
| Your credentials go to | The address that will receive your sign-in. The main part is shown large and bright. For a tool running on your computer, it is usually a local address (http://localhost: and a port). For ChatGPT or Claude in the browser, it is that service's own site. |
| Connection details | Select it to show the client's ID and what it asked for |
| Allow access / Deny | Allow only if you started the client and recognize the address |
Nobody from Selfmade Ninja will ever ask you to approve this screen for them. To learn why the address matters, see How MCP connections are secured.
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.
- Where
- An AI client (for example Claude Code) right after connecting
- What it shows
- 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 see | What to do |
|---|---|
| session not found, failed to connect, or a 404 | The address is wrong. Copy it again from the Setup tab. |
| Unauthorized or 401 | The 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 opens | Your client may need you to start sign-in by hand — follow step 2 · Sign in for your client. |
| A tool is refused because it needs an active labs subscription | Your account has no active labs subscription, so it gets the Free set of tools. |
| A tool is refused because it needs a module that is not enabled | That part of the platform is switched off for your account. Upgrading does not change it; ask your administrator. |
| You are calling tools faster than this platform allows | Your platform limits how many tool calls one account can make in a short time. Wait a moment. Retrying immediately does not help. |
What to ask first
The assistant finds its own way around. It reads the platform's own guide and picks the 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.
Three tools or every tool
Your administrator chooses how the platform lists its tools. Either way the assistant can do exactly the same things, with the same permissions.
| What your client lists | How the assistant works |
|---|---|
Every tool by name, such as list_labs, deploy_lab or write_lab_file | It picks the tool that fits the request. This is the default. |
Three tools: get_service_info, get_type_info and execute_request | It finds the operation, reads its arguments, then runs it. Each answer starts with the operation that ran, for example {"operation": "write_lab_file", ...}. |
Some clients can also show an interactive widget for read tools, such as your lab list. Tools that change something never return a widget.
If the tool list in your client does not match what you expect, reconnect the client: most clients read the list only when they connect.
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 select 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.mdinstead. 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
- Open Account Settings → Security.
- 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.
- Select 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.
Next
- How MCP connections are secured — sign-in, permissions, guard rails
- What you can ask — every area the assistant covers, with example requests
- Worked examples — complete tasks from request to result
- History and safety — what it cannot do, and how to check what it did