> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. # 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 1. In the sidebar, go to **Gateway > Integrations**. 2. Select the **MCP** tab, or use the search box to find your provider. 3. 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 1. In the sidebar, go to **Gateway > Catalog**. 2. Select **Add resource** in the top right. This opens the **Add resource** page. ### Choose the service type and target 1. Under **Service type**, click **MCP**. 2. 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: 1. Go to **Gateway > Routes** and create a route. 2. Set the protocol to **MCP**, attach the service you just created, and set the path or paths callers will use. 3. Choose the route's gateway auth (**Gateway key** or **JWT**) the same way you would if you were [onboarding from **Integrations**](#onboard-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 1. 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. 2. 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. 3. 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. |