Quickstart: Onboard an MCP Server to the Gateway

This guide walks you through registering a Model Context Protocol (MCP) server with the gateway and making it available to your team.

There are two ways to onboard a server:

Use a template from Integrations — Start from a pre-built provider template, such as GitHub, Atlassian, or Notion. Use this option whenever a template exists for your server.
Add a resource directly from Catalog — Register any MCP endpoint by URL. Use this option for internal or custom servers that aren’t in the template catalog.

Both paths create the same underlying object: a gateway service that proxies to your upstream MCP server. From there, you expose the service on a route so your team can use it.

Key concepts

Term	What it is
Integration	A pre-built provider template in the catalog. It describes upstream URLs and supported auth methods, but holds no secrets. Using it creates a service.
Service	The live object that proxies to your upstream MCP server, including its target URL and auth requirements. Appears as a “resource” in Catalog.
Route	The gateway-facing path (or paths) your users call. A route points at one or more services. A server isn’t reachable until it has a route.
Gateway auth	How callers authenticate to the gateway — either a gateway key or a JWT from your identity provider. You configure this on the route.
Upstream credential	The secret (OAuth token, API key, or bearer token) the gateway uses to authenticate to the MCP server. Configure it under Credentials, or let your LLM client prompt you to authorize it the first time a tool call needs it.

There are two independent auth layers here, and it helps to keep them separate:

Caller → Gateway: a gateway key or JWT, set on the route.
Gateway → MCP server: an upstream credential (OAuth, API key, or bearer token).

Prerequisites

Before you begin, make sure you have the following:

Admin access to the gateway UI, with the Manage catalog items permission for onboarding (browsing only requires View permissions).
The upstream MCP server’s HTTPS endpoint URL, if you’re adding a resource directly, or a matching template in Integrations.
For servers that need upstream auth: either the credential itself, or the ability to complete an OAuth sign-in. In most cases you won’t need this up front — your LLM client prompts you to authorize when a tool call needs it, regardless of auth method.
Your data plane URL set in gateway settings, so the UI can generate copy-ready connection links for your routes.

You can onboard from Integrations or Catalog.

Onboard from Integrations

Use this method when a pre-built template already exists for the MCP server you want to add.

Pick a template

In the sidebar, go to Gateway > Integrations.
Select the MCP tab, or use the search box to find your provider.
On the server’s card, click Use integration. The card shows which auth methods it supports — Public, Bearer, API key, or OAuth.

This opens a two-step wizard for creating a service and exposing it through a route.

Create the service

On the Create service step, fill in the following:

Field	What to enter
Service name	A unique, stable identifier for this service. It’s pre-filled from the template, and you can edit it. It must be unique within your organization.
Target URL	The upstream MCP endpoint this service proxies to. Pre-filled from the selected region, and editable.
Region	Only shown when the template offers more than one region. Selecting a region prefills the Target URL.
Auth type	The upstream auth method to use, such as OAuth, Bearer, or API key. Comes from the template.
Applies to	Who provides the upstream credential — Org / tenant for one shared credential, or Each user for a per-user credential. Only shown when the auth type isn’t Public.
Description	Optional.

Select Continue. This creates the service, which now appears under Gateway > Catalog.

Add a route and gateway auth

On the Route & gateway auth step, choose how callers will reach the service:

Create new route — The option to use for a first setup. Enter the following information:
- Route name — A unique, lowercase identifier.
- Paths — The gateway-facing path or paths callers will use, for example /v1/mcp.
- Gateway auth — How callers authenticate to the gateway:
  - No gateway auth — Public at the gateway; not recommended for production.
  - Gateway key — Callers send a provisioned gateway key in a request header (X-Gateway-Key by default).
  - JWT — Callers send a JWT, validated against a configured identity provider.
Connect to existing route — Attach the service to an MCP route you already manage.

Click Finish setup. You’ll see the message “MCP setup complete,” and return to the Integrations page.

Set up upstream credentials (usually not required)

For most MCP servers, you don’t need to pre-create a credential. When a tool call needs authorization, your LLM client surfaces an auth link — complete the sign-in there, and the gateway stores and reuses the credential automatically.

If you’d rather set this up ahead of time, for example, with an API key, a bearer token, or a shared org credential, go to Gateway > Credentials > Create credential and provide the secret. For OAuth servers, the gateway discovers OAuth metadata from the upstream automatically.

If you chose Gateway key for gateway auth in the previous step, provision those keys under Credentials too.

Add a resource directly from Catalog

Use this method for internal or custom MCP servers that aren’t in the template catalog.

Open the create page

In the sidebar, go to Gateway > Catalog.
Select Add resource in the top right. This opens the Add resource page.

Choose the service type and target

Under Service type, click MCP.
Fill in the following fields:

Field	What to enter
Name	A unique, DNS-like identifier, for example `internal-crm`. Must be unique within your organization.
Target URL	The HTTPS MCP endpoint, for example `https://mcp.svc.internal/mcp`. If you omit the scheme, `https://` is assumed.

You don’t need to choose a transport type — the gateway talks to the upstream over HTTP and automatically handles both JSON and SSE (streamable-HTTP) responses.

Set up upstream auth (optional)

If the upstream MCP server requires credentials, turn on Upstream auth requirement and set:

Field	What to enter
Auth type	Bearer, API key header, or OAuth.
Applies to	Org / tenant, or Each user, depending on who supplies the credential.
Header name	For API key auth only — the upstream header name, for example `X-Api-Key`. You’ll add the value itself later, under Credentials.

Leave this section off for MCP servers that don’t need auth. Select Add Resource. You’ll see the message “Service created,” and the new server appears on the MCPs tab in Catalog.

Add a route

A directly-added resource has no route yet, so it isn’t reachable until you add one:

Go to Gateway > Routes and create a route.
Set the protocol to MCP, attach the service you just created, and set the path or paths callers will use.
Choose the route’s gateway auth (Gateway key or JWT) the same way you would if you were onboarding from Integrations.

Set up upstream credentials (usually not required)

As with the Integrations method, you generally don’t need to pre-create a credential. When a tool call needs authorization, your LLM client provides an auth link, and you complete the sign-in there. If you turned on an upstream auth requirement and want to configure it ahead of time, add the matching credential under Gateway > Credentials > Create credential.

Connect your users

In Gateway > Routes, use the row’s Copy DP URL action to get the connection URL (your data plane URL plus the route path), for example https://gateway.example.com/v1/mcp/.

Set your data plane URL in gateway settings first. Without it, the copy action won’t produce a usable link.
Configure the MCP client with the copied URL, and set gateway auth to match how the route was set up — either the gateway key header or a JWT.
Authorize upstream access when prompted. Regardless of auth method, the client surfaces an auth link the first time a tool call needs it. Completing the sign-in lets the gateway obtain and store the upstream credential. If a credential was already pre-provisioned under Credentials, it’s used automatically and no prompt appears.

Users can review their available resources and connection details under My access.

Which method should I use?

Use Integrations when…	Use Add resource when…
A template exists for your provider.	The server is internal or custom, with no template.
You want auth methods and target URLs pre-filled.	You want to register any MCP endpoint by URL.
You want a guided two-step wizard for the service and route.	You’re comfortable adding the route as a separate step.

Troubleshooting

If you see this…	Try this
The server doesn’t appear for users	Confirm it has a route. A service with no route isn’t reachable.
Users get `401`	Check that they’re passing valid gateway auth. A gateway key or JWT may be missing or incorrect.
Upstream auth errors	Complete the auth link your LLM client surfaces, or pre-provision the matching credential under Credentials.
You can’t copy a connection URL	Set your data plane URL in gateway settings.