MCP Gateway

Getting Started with MCP Gateway - Portal

MCP Gateway tutorialZuplo Portal

Connect an MCP client to Linear through your own gateway and call a Linear tool.

Follow along using

Build a Zuplo MCP Gateway fronting Linear at https://<your-gateway>/mcp/linear-v1, entirely in the browser. By the end, Claude Desktop signs in through your identity provider, connects your Linear account over the gateway's per-user OAuth flow, and answers "list my open Linear issues" with real results, logged in your analytics.

The MCP Gateway Virtual Server wizard scaffolds the route and policies for you: pick an upstream, an identity provider, what to expose, and how to authenticate upstream. This guide uses Linear and Auth0, but the wizard supports any upstream in its library (plus custom servers) and every identity provider Zuplo wraps.

Prefer the CLI? The local quickstart reaches the same result on your machine.

Prerequisites

A free Zuplo account.
An account with your identity provider. For the Auth0 example, that's an Auth0 tenant with a Regular Web Application configured. The Configuring Auth0 guide covers the dashboard side. From it you'll need the domain, client ID, and client secret.

Create and test your MCP Gateway

Create a Zuplo project

In the Zuplo Portal, open Projects, click New Project, and select API & MCP Gateway. Name the project my-mcp-gateway, choose a blank project rather than importing one, and click Create Project. The project opens on the Project tab.
Start an MCP Gateway Virtual Server

Open the Code tab in the project you created.

Click Add to Gateway (or Add Route if the project already has routes), then choose MCP Gateway Virtual Server from the menu.

The New MCP Gateway Virtual Server wizard opens and walks through four steps: the upstream server, inbound auth, tools, and outbound auth.
Choose the upstream MCP server

On the Upstream step, pick the MCP server this virtual server fronts. Select Linear from the Library of pre-configured servers. The Name and MCP URL (https://mcp.linear.app/mcp) fill in automatically, and the Path defaults to /mcp/linear-v1. These fields are editable, but a pre-configured server already has the correct MCP URL, so leave it as-is. Click Next.

The Custom tab lets you point at your own MCP server or any third-party server that isn't in the library. Just supply its name and MCP URL.
Choose an identity provider

The Inbound Auth step controls how MCP clients authenticate to the gateway. Pick your identity provider; this guide uses Auth0. The wizard scaffolds a new inbound OAuth policy for that provider. Click Next.

Not using Auth0?
The catalog includes WorkOS, Google, Okta, Microsoft Entra, Cognito, Clerk, Keycloak, Logto, OneLogin, and PingOne. You can also select an existing inbound policy, or pick None if this route doesn't need gateway OAuth. See the provider catalog.
Decide what the virtual server exposes

The Tools step controls which tools, prompts, and resources the virtual server exposes to its clients:
- Passthrough federates the upstream's catalog live. Zero config, and the safest default. Everything the upstream offers is exposed.
- Filter & curate lets you pick specific tools, prompts, and resources. Use this to control what users can do. For example, drop all destructive tools and expose only read and write tools.
Choose Passthrough and click Next.

Curate requires signing in to the upstream service so the wizard can enumerate the catalog to pick from. Passthrough needs no sign-in.
Configure upstream authentication

On Outbound Auth, leave User OAuth selected so each user connects their own Linear account. Click Next.

Leave OAuth client registration set to Dynamic. The gateway registers with Linear automatically, so you don't need a Linear client ID or secret. Click Finish.

Upstream doesn't use OAuth?
Pick None when the upstream doesn't require authentication. If gateway OAuth is enabled, the gateway validates and removes its access token before forwarding the request. It doesn't use that token to authenticate upstream.

The wizard adds the new MCP route to config/routes.oas.json and scaffolds the inbound auth and token-exchange policies. Save the project.
Set your identity provider's environment variables

In config/policies.json, set the Auth0 policy's environment variable references to match these names, then save the file:
```
Code
{
  "auth0Domain": "$env(AUTH0_DOMAIN)",
  "clientId": "$env(AUTH0_CLIENT_ID)",
  "clientSecret": "$env(AUTH0_CLIENT_SECRET)"
}
```
Open your project's Settings from the navigation bar, then click Environment Variables under Project Settings.

Add one variable per credential. For the Auth0 example:

Name Value Secret?
AUTH0_DOMAIN your-tenant.us.auth0.com No
AUTH0_CLIENT_ID your application client ID Yes
AUTH0_CLIENT_SECRET your application secret Yes

Check the Secret box for the client ID and secret so their values are hidden in the encrypted secret store. AUTH0_DOMAIN isn't sensitive, so leave it unchecked. Click Save for each.

A new deployment is needed for environment variable changes to take effect.

AUTH0_DOMAIN is a bare hostname (my-tenant.us.auth0.com), not a URL.

Using a different provider?
Set whatever variables your provider's scaffolded policy expects instead. The policy in config/policies.json shows the $env(...) references it reads.
Verify the OAuth policy is wired up

Click the Test button next to the route's path and send a POST with no Authorization header. You should get a 401 Unauthorized whose WWW-Authenticate header challenges for OAuth. Example:
```
Code
WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://<your-zuplo-gateway>/.well-known/oauth-protected-resource/mcp/linear-v1", scope="mcp:tools"
```
(<your-zuplo-gateway> is your deployment's host.) That 401 is the gateway telling a future MCP client "you need to authenticate first." It confirms the OAuth policy is loaded. If you see a 200, 404, or 500, the OAuth policy isn't attached to the route.

Test with the MCP Inspector
The Test panel also shows a ready-to-run MCP Inspector command with your route's URL pre-filled. Copy it, run it in your terminal, and step through the full OAuth flow against the live route.
Connect Claude Desktop

Your route is live at https://<your-gateway>/mcp/linear-v1. Find the public URL via the Gateway deployed button in the toolbar.

Open Claude Desktop, go to Customize → Connectors, click +, then Add custom connector. Paste the route URL and click Add.

Claude Desktop opens the gateway's OAuth flow in a browser:
1. Sign in with your identity provider (Auth0 in this example).
2. The gateway's consent page lists Linear with a Connect button.
3. Click Connect, complete Linear's OAuth flow, then click Authorize to finish.
Checkpoint: Claude is connected
Back in Claude Desktop, the new connector appears in Customize → Connectors marked as connected. Subsequent requests reuse the tokens the gateway just issued.

For per-client setup details, see Connect MCP clients.
Test it

In Claude Desktop, prompt the model with something that requires Linear. "list my open issues" works well. Claude asks for permission to call the tool, then returns results proxied through the gateway.

Open the project's Observability → Analytics view and select the MCP section to see the call appear in the events timeline, the success rate, the top capabilities table, and the user breakdown.

Name	Value	Secret?
`AUTH0_DOMAIN`	`your-tenant.us.auth0.com`	No
`AUTH0_CLIENT_ID`	your application client ID	Yes
`AUTH0_CLIENT_SECRET`	your application secret	Yes

You now have a working MCP Gateway in front of Linear: Claude Desktop authenticates against your identity provider, the gateway exchanges that for a per-user Linear token, and every call lands in your analytics. Run the wizard again for each additional upstream you want to front.

Deploy to production before sharing

The Working Copy (Development) URLs are fine for testing everything above. Once you've confirmed the virtual server works, set up a production deployment via environments before giving others access. The development URL is tied to your working copy and isn't meant for shared or production traffic.

Next steps

Connect more clients: Claude Code, Cursor, VS Code, ChatGPT, and any other MCP client.
How it works: the request lifecycle and the two OAuth surfaces.
Capability filtering: go deeper on the Curate option, overriding tool descriptions and annotations, not just include/exclude.
Add more upstreams: front several upstream MCP servers from one Zuplo project.

Getting Started Getting Started with MCP Gateway - Editor

Create and test your MCP Gateway

Create a Zuplo project

In the Zuplo Portal, open Projects, click New Project, and select API & MCP Gateway. Name the project my-mcp-gateway, choose a blank project rather than importing one, and click Create Project. The project opens on the Project tab.
Start an MCP Gateway Virtual Server

Open the Code tab in the project you created.

Click Add to Gateway (or Add Route if the project already has routes), then choose MCP Gateway Virtual Server from the menu.

The New MCP Gateway Virtual Server wizard opens and walks through four steps: the upstream server, inbound auth, tools, and outbound auth.
Choose the upstream MCP server

On the Upstream step, pick the MCP server this virtual server fronts. Select Linear from the Library of pre-configured servers. The Name and MCP URL (https://mcp.linear.app/mcp) fill in automatically, and the Path defaults to /mcp/linear-v1. These fields are editable, but a pre-configured server already has the correct MCP URL, so leave it as-is. Click Next.

The Custom tab lets you point at your own MCP server or any third-party server that isn't in the library. Just supply its name and MCP URL.
Choose an identity provider

The Inbound Auth step controls how MCP clients authenticate to the gateway. Pick your identity provider; this guide uses Auth0. The wizard scaffolds a new inbound OAuth policy for that provider. Click Next.

Not using Auth0?
The catalog includes WorkOS, Google, Okta, Microsoft Entra, Cognito, Clerk, Keycloak, Logto, OneLogin, and PingOne. You can also select an existing inbound policy, or pick None if this route doesn't need gateway OAuth. See the provider catalog.
Decide what the virtual server exposes

The Tools step controls which tools, prompts, and resources the virtual server exposes to its clients:
- Passthrough federates the upstream's catalog live. Zero config, and the safest default. Everything the upstream offers is exposed.
- Filter & curate lets you pick specific tools, prompts, and resources. Use this to control what users can do. For example, drop all destructive tools and expose only read and write tools.
Choose Passthrough and click Next.

Curate requires signing in to the upstream service so the wizard can enumerate the catalog to pick from. Passthrough needs no sign-in.
Configure upstream authentication

On Outbound Auth, leave User OAuth selected so each user connects their own Linear account. Click Next.

Leave OAuth client registration set to Dynamic. The gateway registers with Linear automatically, so you don't need a Linear client ID or secret. Click Finish.

Upstream doesn't use OAuth?
Pick None when the upstream doesn't require authentication. If gateway OAuth is enabled, the gateway validates and removes its access token before forwarding the request. It doesn't use that token to authenticate upstream.

The wizard adds the new MCP route to config/routes.oas.json and scaffolds the inbound auth and token-exchange policies. Save the project.
Set your identity provider's environment variables

In config/policies.json, set the Auth0 policy's environment variable references to match these names, then save the file:
```
Code
{
  "auth0Domain": "$env(AUTH0_DOMAIN)",
  "clientId": "$env(AUTH0_CLIENT_ID)",
  "clientSecret": "$env(AUTH0_CLIENT_SECRET)"
}
```
Open your project's Settings from the navigation bar, then click Environment Variables under Project Settings.

Add one variable per credential. For the Auth0 example:

Name Value Secret?
AUTH0_DOMAIN your-tenant.us.auth0.com No
AUTH0_CLIENT_ID your application client ID Yes
AUTH0_CLIENT_SECRET your application secret Yes

Check the Secret box for the client ID and secret so their values are hidden in the encrypted secret store. AUTH0_DOMAIN isn't sensitive, so leave it unchecked. Click Save for each.

A new deployment is needed for environment variable changes to take effect.

AUTH0_DOMAIN is a bare hostname (my-tenant.us.auth0.com), not a URL.

Using a different provider?
Set whatever variables your provider's scaffolded policy expects instead. The policy in config/policies.json shows the $env(...) references it reads.
Verify the OAuth policy is wired up

Click the Test button next to the route's path and send a POST with no Authorization header. You should get a 401 Unauthorized whose WWW-Authenticate header challenges for OAuth. Example:
```
Code
WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://<your-zuplo-gateway>/.well-known/oauth-protected-resource/mcp/linear-v1", scope="mcp:tools"
```
(<your-zuplo-gateway> is your deployment's host.) That 401 is the gateway telling a future MCP client "you need to authenticate first." It confirms the OAuth policy is loaded. If you see a 200, 404, or 500, the OAuth policy isn't attached to the route.

Test with the MCP Inspector
The Test panel also shows a ready-to-run MCP Inspector command with your route's URL pre-filled. Copy it, run it in your terminal, and step through the full OAuth flow against the live route.
Connect Claude Desktop

Your route is live at https://<your-gateway>/mcp/linear-v1. Find the public URL via the Gateway deployed button in the toolbar.

Open Claude Desktop, go to Customize → Connectors, click +, then Add custom connector. Paste the route URL and click Add.

Claude Desktop opens the gateway's OAuth flow in a browser:
1. Sign in with your identity provider (Auth0 in this example).
2. The gateway's consent page lists Linear with a Connect button.
3. Click Connect, complete Linear's OAuth flow, then click Authorize to finish.
Checkpoint: Claude is connected
Back in Claude Desktop, the new connector appears in Customize → Connectors marked as connected. Subsequent requests reuse the tokens the gateway just issued.

For per-client setup details, see Connect MCP clients.
Test it

In Claude Desktop, prompt the model with something that requires Linear. "list my open issues" works well. Claude asks for permission to call the tool, then returns results proxied through the gateway.

Open the project's Observability → Analytics view and select the MCP section to see the call appear in the events timeline, the success rate, the top capabilities table, and the user breakdown.

Name	Value	Secret?
`AUTH0_DOMAIN`	`your-tenant.us.auth0.com`	No
`AUTH0_CLIENT_ID`	your application client ID	Yes
`AUTH0_CLIENT_SECRET`	your application secret	Yes

Deploy to production before sharing

Next steps

Connect more clients: Claude Code, Cursor, VS Code, ChatGPT, and any other MCP client.

How it works: the request lifecycle and the two OAuth surfaces.

Capability filtering: go deeper on the Curate option, overriding tool descriptions and annotations, not just include/exclude.

Add more upstreams: front several upstream MCP servers from one Zuplo project.