zuplo 6.70.56 → 6.70.59

package/docs/mcp-gateway/quickstart-local.mdx

@@ -0,0 +1,291 @@
+---
+title: "MCP Gateway quickstart (Local Dev)"
+sidebar_label: "Quickstart (Local Dev)"
+description:
+  Build an MCP Gateway locally with the Zuplo CLI. Register the plugin, add one
+  upstream MCP server, run it with the loopback dev-login shortcut, and connect
+  Claude Desktop. No identity provider setup required to start.
+---
+
+<QuickstartPicker mode="local" alternateLink="/mcp-gateway/quickstart" />
+
+Build a Zuplo MCP Gateway fronting Linear, running locally at
+`http://127.0.0.1:9000/mcp/linear-v1`. By the end, Claude Desktop connects over
+the gateway's per-user OAuth flow and answers "list my open Linear issues" with
+real results.
+
+Any Zuplo project becomes a gateway by adding a plugin, a couple of policies,
+and a route. This guide uses Linear as the upstream and the built-in
+**dev-login** shortcut for sign-in, so you skip identity-provider setup to try
+it out. For production, swap in your provider: the gateway wraps Auth0, Okta,
+Microsoft Entra, Google, Clerk, Cognito, Keycloak, Logto, OneLogin, PingOne, and
+WorkOS, plus a generic OIDC fallback. See the
+[provider catalog](./auth/overview.mdx#identity-providers).
+
+Prefer the browser with no local setup? The
+[Portal quickstart](./quickstart.mdx) reaches the same result through the Zuplo
+Portal UI.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download) 20 or higher.
+- A local Zuplo project. Create an empty one with:
+
+  ```bash
+  npx create-zuplo-api@latest --empty
+  ```
+
+  Then `cd` into the new directory. See
+  [`create-zuplo-api`](../cli/create-zuplo-api.mdx) for other options, or
+  [import an existing portal project](../articles/local-development.mdx#import-your-existing-project)
+  by connecting it to Git and cloning it.
+
+:::note
+
+New projects created with `create-zuplo-api` ship a recent `compatibilityDate`,
+so MCP Gateway features work out of the box. If you're adding the gateway to an
+older project and the build complains about the compatibility date, see
+[Compatibility dates](./code-config/compatibility-dates.mdx).
+
+:::
+
+<Stepper>
+
+1. **Register the MCP Gateway plugin**
+
+   Open `modules/zuplo.runtime.ts` (create it if it doesn't exist) and register
+   `McpGatewayPlugin`:
+
+   ```ts title="modules/zuplo.runtime.ts"
+   import { RuntimeExtensions } from "@zuplo/runtime";
+   import { McpGatewayPlugin } from "@zuplo/runtime/mcp-gateway";
+
+   export function runtimeInit(runtime: RuntimeExtensions) {
+     runtime.addPlugin(new McpGatewayPlugin());
+   }
+   ```
+
+   The plugin registers the OAuth metadata, authorization endpoints, consent
+   page, and upstream connect callbacks the gateway needs.
+
+2. **Add an OAuth policy with the dev-login shortcut**
+
+   Setting up a real identity provider for local development is friction. You'd
+   register a loopback callback, manage test users, and so on. The gateway
+   exposes a loopback-only shortcut that skips the IdP round-trip entirely and
+   signs you in as a fixed `dev-browser-user`.
+
+   Open `config/policies.json` and add the generic OAuth policy pointed at the
+   dev-login URL:
+
+   ```json title="config/policies.json"
+   {
+     "name": "dev-oauth",
+     "policyType": "mcp-oauth-inbound",
+     "handler": {
+       "module": "$import(@zuplo/runtime/mcp-gateway)",
+       "export": "McpOAuthInboundPolicy",
+       "options": {
+         "oidc": {
+           "issuer": "http://127.0.0.1:9000",
+           "jwksUrl": "http://127.0.0.1:9000/.well-known/jwks.json"
+         },
+         "browserLogin": {
+           "url": "http://127.0.0.1:9000/oauth/dev-login"
+         }
+       }
+     }
+   }
+   ```
+
+   :::caution
+
+   `/oauth/dev-login` returns `403 Forbidden` for any request that doesn't
+   arrive over loopback, so it's safe to leave configured, but only useful in
+   local dev. Production deployments should use a real OIDC provider through one
+   of the [IdP wrappers](./auth/overview.mdx#identity-providers). A common
+   pattern is keeping two OAuth policies (one for production, one for dev) and
+   selecting between them in `routes.oas.json` by environment.
+
+   :::
+
+   When you do switch to a real provider, its policy reads credentials from
+   `$env(...)` references. Define those values in a `.env` file at the project
+   root:
+
+   ```bash title=".env"
+   MCP_AUTH0_DOMAIN=your-tenant.us.auth0.com
+   MCP_AUTH0_CLIENT_ID=your-auth0-web-app-client-id
+   MCP_AUTH0_CLIENT_SECRET=your-auth0-web-app-client-secret
+   ```
+
+   `.env` is read when `npm run dev` starts, so restart the dev server after
+   adding or changing a variable. Never commit `.env`. Check in a `.env.example`
+   with placeholder values instead. The dev-login shortcut above needs no
+   environment variables, so you can skip this until you wire up a provider.
+
+3. **Add a token-exchange policy for the upstream**
+
+   Each OAuth-protected upstream gets its own `mcp-token-exchange-inbound`
+   policy. It looks up the user's upstream credential and attaches it as the
+   upstream `Authorization` header. Add this entry to `config/policies.json`:
+
+   ```json title="config/policies.json"
+   {
+     "name": "mcp-token-exchange-linear",
+     "policyType": "mcp-token-exchange-inbound",
+     "handler": {
+       "module": "$import(@zuplo/runtime/mcp-gateway)",
+       "export": "McpTokenExchangeInboundPolicy",
+       "options": {
+         "displayName": "Linear",
+         "protectedResourceMetadataUrl": "https://mcp.linear.app/.well-known/oauth-protected-resource",
+         "authMode": "user-oauth",
+         "scopes": [],
+         "clientRegistration": { "mode": "auto" }
+       }
+     }
+   }
+   ```
+
+   `authMode: "user-oauth"` means each user connects their own Linear account
+   the first time they call the route. `clientRegistration: { "mode": "auto" }`
+   lets the gateway register itself with Linear's OAuth server on demand, so no
+   upstream client credentials in source control.
+
+4. **Add the route**
+
+   Open `config/routes.oas.json` and add an MCP route. The handler points at
+   Linear's MCP server URL; the inbound policy chain runs the OAuth policy
+   followed by the token-exchange policy:
+
+   ```json title="config/routes.oas.json"
+   {
+     "openapi": "3.1.0",
+     "info": { "title": "MCP Gateway", "version": "0.1.0" },
+     "paths": {
+       "/mcp/linear-v1": {
+         "get,post": {
+           "operationId": "linear-mcp-server",
+           "summary": "Linear MCP Proxy",
+           "x-zuplo-route": {
+             "corsPolicy": "none",
+             "handler": {
+               "module": "$import(@zuplo/runtime/mcp-gateway)",
+               "export": "McpProxyHandler",
+               "options": {
+                 "rewritePattern": "https://mcp.linear.app/mcp"
+               }
+             },
+             "policies": {
+               "inbound": ["dev-oauth", "mcp-token-exchange-linear"]
+             }
+           }
+         }
+       }
+     }
+   }
+   ```
+
+   `operationId` is the stable identifier for the route. It appears in analytics
+   and is part of the per-user upstream connection key, so pick it once and
+   don't change it. The path is whatever you set; `/mcp/<provider>-v<n>` is the
+   convention.
+
+5. **Run the gateway**
+
+   From the project root:
+
+   ```bash
+   npm run dev
+   ```
+
+   The route is now reachable at `http://127.0.0.1:9000/mcp/linear-v1`.
+
+   :::tip{title="Checkpoint: confirm the OAuth policy is wired up"}
+
+   Send an unauthenticated POST and expect a `401`:
+
+   ```bash
+   curl -i -X POST http://127.0.0.1:9000/mcp/linear-v1 \
+     -H "Content-Type: application/json" \
+     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+   ```
+
+   The response should be `401 Unauthorized` with a `WWW-Authenticate: Bearer`
+   header pointing at `/.well-known/oauth-protected-resource/mcp/linear-v1`.
+   That 401 confirms the OAuth policy is loaded. If you see a 200, 404, or 500
+   instead, the OAuth policy isn't attached to the route.
+
+   :::
+
+   :::caution{title="Use 127.0.0.1, not localhost"}
+
+   OAuth metadata and callback URLs key off the request origin. Other loopback
+   aliases (`localhost`, `::1`) can break OAuth subtly in local dev. See
+   [Local development](./code-config/local-development.mdx) for the full set of
+   local-only details, including the known `workerd` restart quirk.
+
+   :::
+
+6. **Connect Claude Desktop**
+
+   Open Claude Desktop, go to **Settings → Connectors**, scroll to the bottom,
+   and click **Add custom connector**. Paste
+   `http://127.0.0.1:9000/mcp/linear-v1` and click **Add**.
+
+   Claude Desktop opens the gateway's OAuth flow in a browser:
+   1. The dev-login shortcut signs you in without any IdP prompt.
+   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.
+
+   :::tip{title="Checkpoint: Claude is connected"}
+
+   Back in Claude Desktop, the new connector appears in **Settings →
+   Connectors** marked as connected. Subsequent requests reuse the tokens the
+   gateway just issued.
+
+   :::
+
+   For per-client setup details, see
+   [Connect MCP clients](./connect-clients/overview.mdx).
+
+7. **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.
+
+</Stepper>
+
+You now have a working MCP Gateway in front of Linear, running locally: Claude
+Desktop signs in through the dev-login shortcut, the gateway exchanges that for
+a per-user Linear token, and every call is proxied through. The same shape (one
+OAuth policy, one token-exchange policy per upstream, one route per upstream)
+scales out to as many upstream MCP servers as you want to front.
+
+:::caution{title="Deploy to production before sharing"}
+
+The local gateway on `127.0.0.1` is for development only, and the dev-login
+shortcut works over loopback alone. Before giving others access, swap in a real
+identity provider and ship the gateway through the Zuplo Portal. See
+[environments](../articles/environments.mdx) for setting up a production
+deployment.
+
+:::
+
+## Next steps
+
+- [Deploy from the Portal](./quickstart.mdx): swap the dev-login shortcut for a
+  real identity provider and ship the gateway through the Zuplo Portal.
+- [Local development](./code-config/local-development.mdx): the dev-login
+  shortcut in depth, environment variables, and local-only quirks.
+- [Connect more clients](./connect-clients/overview.mdx): Claude Code, Cursor,
+  VS Code, ChatGPT, and any other MCP client.
+- [How it works](./how-it-works.mdx): the request lifecycle and the two OAuth
+  surfaces.
+- [Add more upstreams](./code-config/multi-upstream.mdx): front several upstream
+  MCP servers from one Zuplo project.
+- [Capability filtering](./capability-filtering.mdx): curate the tools, prompts,
+  and resources each route exposes.