MCP servers guide
How to register upstream MCP servers and discover their tools.
Overview
MCP Servers are upstream Model Context Protocol servers that Cortega exposes through the gateway. Registering a server tells Cortega where the server is, how to authenticate to it, and whether it should be rendered into gateway config.
MCP Servers do not assign caller teams. Teams come from Identities and MCP Authorization.
Add an MCP server
Navigate to AI Border Gateway → MCP.
- Click Add Server.
- Enter a server name.
- Select the transport.
- Enter the endpoint or command details.
- Select upstream auth, if the upstream server requires it.
- Save.
Transport choices
| Transport | Use when |
|---|---|
| Streamable HTTP | The MCP server exposes the streamable HTTP transport |
| HTTP SSE | The MCP server uses Server-Sent Events |
| Stdio | You want to store a local command-based MCP server definition |
Enabled HTTP servers are rendered into gateway config. Stdio server records are stored, but the current gateway target render path only includes HTTP transports.
Enable or disable a server
Use the Enabled toggle on the MCP Servers table.
| State | Result |
|---|---|
| Enabled | Rendered into gateway config if it uses an HTTP transport |
| Disabled | Removed from gateway config |
The legacy approval field is informational. Rendering is controlled by Enabled.
Upstream auth
Choose upstream auth based on how Cortega should authenticate when it forwards calls to the server.
Common options:
| Auth type | Use when |
|---|---|
| None | The upstream server needs no auth |
| API key | Cortega should attach a stored key to upstream calls |
| Client-supplied upstream credential | The client sends its own credential for this server in a request header; Cortega never stores it |
| Copilot | The upstream is GitHub Copilot MCP |
| GCP / AWS / Azure implicit | The gateway environment supplies cloud identity |
API keys are encrypted at rest and rendered as secret references.
Choose Client-supplied upstream credential when the client brings its
own credential for the upstream server. The client still authenticates to
Cortega with an MCP identity; it sends the server credential in the
upstream-credential header, and Cortega forwards that value as the
upstream Authorization and strips the header before the call. See
Pass-through routing for the safety
rules and the stored-credential override.
Discover tools
Tool discovery reads the upstream server's current tool list and stores it in Cortega.
Use discovery when:
- you first register a server
- an upstream server adds or removes tools
- MCP Authorization needs current tool checkboxes
You can discover tools for one server, or use Get All Tools where available.
Discovery updates existing tools and removes tools that no longer exist on that server. Existing MCP Authorization selections are preserved when the same tool remains present.
SSE servers
For HTTP SSE servers, Cortega initializes the SSE connection first and
posts JSON-RPC messages to the server-provided message endpoint. Directly
posting initialize to an SSE URL can return 404.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Server does not appear in gateway config | Disabled, non-HTTP transport, or global MCP toggle off | Check server Enabled state and transport |
| Tool discovery returns 404 | SSE endpoint was treated as direct POST endpoint | Confirm server transport is HTTP SSE |
| No tools appear under MCP Authorization | Tools have not been discovered yet | Run discovery for the server |
| Upstream call fails auth | Wrong upstream auth type or missing credential | Edit server upstream auth settings |