Connecting MCP servers
People and agents reach every MCP server through one address on the gateway,
https://gateway.aigw.app/mcp/<server>, with their aigw key. aigw checks the
call against your tool policy, records it, and
then calls the server with the credential that server needs. Choosing that
credential is what this page is about: it is set per server, under Tools >
the server > Auth.
How aigw signs in to a server
| Auth | What the server receives | Use it for |
|---|---|---|
| None | Nothing | Open servers, and servers inside your network |
| Bearer token | Authorization: Bearer <token> | A server with one API token |
| API key (named header) | Your header, e.g. X-API-Key | A server that takes a key in its own header |
| Basic | User and password | Older internal services |
| OAuth2 (client credentials) | A token aigw fetches and renews | A server that trusts a service identity from your IdP |
| On behalf of the caller | A token exchanged for the person’s own (Entra on-behalf-of, or RFC 8693) | Your own servers that trust your IdP, when callers arrive with an IdP token |
| Each person connects their own account | That person’s own token at the server | SaaS servers where everyone has their own account: Miro, LeanIX, GitHub, Atlassian |
| mTLS | A client certificate | Servers that require one |
Secrets are sealed when you save them and only the gateway opens them. The console never shows them again; it shows that one is on file.
Every option except the last presents one credential for everybody, so the server sees aigw, not a person, and applies that one account’s permissions. aigw still records who made each call. When the server itself has to see the person, use per-person connections.
Per-person connections
With Each person connects their own account, everyone signs in to the server once with their own account, and aigw calls the server as them from then on. People keep using only their aigw key; they never handle the server’s tokens.
What an admin sets
Choose Each person connects their own account under Auth. That is usually all: aigw finds the server’s sign-in from the server itself (the MCP authorization standard) and registers itself there.
- Client ID: only for a server whose sign-in does not let aigw register
itself. Register an app at the vendor with the redirect URI
https://api.aigw.app/connect/callback, and enter its client ID and secret here. If one is needed, the person’s first sign-in says so. - Scopes: optional. By default aigw asks for what the server says it needs.
Each person needs their own aigw key. A connection belongs to the person a key belongs to, so a key shared between people would share one person’s account. People can create their own key under Access.
What a person sees
The first time someone uses the server, it is there but not yet connected. In Claude Code, Cursor or any MCP client, it offers one tool, connect_<server>. Ask for anything on that server and the assistant calls it and shows the link:
- Open the link. The page says what is being connected and for which key.
- Click Continue to sign in and sign in at the server’s own login page. If your company uses single sign-on at that vendor, this is usually one click.
- The page says Connected. Ask again: the server’s real tools are there now.
Behind step 3, aigw ends the stand-in session and the client opens a new one against the real server. That is part of the MCP transport, so no client needs reconnecting by hand.
A client that supports MCP’s URL elicitation (-32042) offers the same link
as a sign-in prompt when a real tool is called without a connection.
After connecting
- Renewal is silent. aigw renews the person’s token before it expires, for as long as the server allows.
- When the server ends a connection (the person revoked aigw there, or left the company), the next call hands the link back with the reason.
- Agents and services connect on their own. An agent key, even one a person created, has its own connection and never acts as its creator.
- Admins see who has connected each server under Tools > the server > Connected, and can disconnect anyone. aigw stops presenting that token at once; the person is asked to connect again on their next call.
Signing in to aigw from an MCP client
Separately from how aigw signs in to servers, people can sign in to aigw from their MCP client with your company’s single sign-on, instead of using a key. aigw then knows each person and their groups on every tool call, and tool access can be granted by group.
- Set up Settings > Access & security > Single sign-on with your
identity provider, and verify your email domain with the DNS record shown.
For Microsoft Entra: register an app with the redirect URI
https://api.aigw.app/v1/auth/sso/callback, add a client secret, and for group-based access add the groups claim. Grant admin consent for the app if your users cannot consent themselves: aigw asks for offline access so it can check back with Entra. - Turn on Sign in from MCP clients in the same section.
- People add
https://gateway.aigw.app/mcp/<workspace>/all(every server) or.../<workspace>/<server>(one) in their client, which opens the sign-in.
aigw checks each sign-in with your identity provider every few minutes:
someone disabled there loses access at their next renewal, and group changes
apply then. A person in more groups than Entra puts in a token keeps their
groups: aigw reads them from Microsoft Graph with the sign-in’s own User.Read.
This sign-in and per-person connections work together: a person signed in with SSO has their own connections, as with their own key.
When something goes wrong
Every failure comes back as an MCP error that names the server and the reason, so the client can show it:
- “<server> refused the credential aigw presented”: the server’s Auth is wrong or the secret has expired. Check it under Tools.
- “<server> is unavailable (HTTP 503)”: the server is down. Its own message follows.
- “aigw could not reach <server>”: the address is wrong, or the server is not reachable from the gateway.
- “this server’s sign-in does not let aigw register itself”: add a client ID for it (see above).
Self-hosted gateways
Everything here works on a self-hosted gateway. For per-person connections, the people’s tokens are held sealed by aigw’s control plane and handed to your gateway per call, sealed to it. Keeping them only on your gateway is on the roadmap.