Cross App Access quickstart

Create a Zuplo project.

In the Zuplo Portal, select New Project and create an empty API Gateway project. Name it xaa-quick-start.

On the project Overview page, copy the deployment URL shown at the top (for example, https://xaa-quick-start-main-abc1234.d2.zuplo.dev). This is your gateway's public origin — you'll need it for the next two steps.

Register a requesting app on xaa.dev.

Sign in to xaa.dev and open the developer registration page. Enter your email, then select Register New App and fill in:

• Application Name — anything, for example xaa-quick-start gateway.

• Redirect URIs — your gateway's OAuth callback:

  Code
  https://your-gateway.zuplo.dev/__zuplo/oauth/callback

Under Resource Connections, select Todo0 MCP Server, keep both scopes (todos.read and mcp.access) checked, and select Add Connection. Then select Register App.

Registration shows four values. Copy all of them — the secrets are shown only once:

Add the gateway configuration.

Open the project's code editor (the Code tab). The gateway needs three files.

First, define the two policies. Open config/policies.json (use the raw policies.json tab, not the visual Policy List) and replace its contents:

config/policies.json
{
  "policies": [
    {
      "name": "xaa-inbound",
      "policyType": "mcp-oauth-inbound",
      "handler": {
        "module": "$import(@zuplo/runtime/mcp-gateway)",
        "export": "McpOAuthInboundPolicy",
        "options": {
          "oidc": {
            "issuer": "https://idp.xaa.dev",
            "jwksUrl": "https://idp.xaa.dev/jwks",
            "audience": "$env(GATEWAY_AUDIENCE)"
          },
          "browserLogin": {
            "url": "https://idp.xaa.dev/authorize",
            "tokenUrl": "https://idp.xaa.dev/token",
            "clientId": "$env(XAA_CLIENT_ID)",
            "clientSecret": "$env(XAA_CLIENT_SECRET)",
            "scope": "openid profile email",
            "audience": "$env(GATEWAY_AUDIENCE)",
            "pkce": "S256"
          }
        }
      }
    },
    {
      "name": "id-jag-upstream",
      "policyType": "mcp-token-exchange-inbound",
      "handler": {
        "module": "$import(@zuplo/runtime/mcp-gateway)",
        "export": "McpTokenExchangeInboundPolicy",
        "options": {
          "id": "id-jag-upstream",
          "displayName": "Todo0",
          "summary": "xaa.dev Todo0 MCP server, reached via Cross App Access (ID-JAG).",
          "authMode": "id-jag",
          "idJag": {
            "scopes": ["todos.read", "mcp.access"],
            "idp": {
              "tokenUrl": "https://idp.xaa.dev/token",
              "clientAuth": {
                "method": "client_secret_post",
                "clientId": "$env(XAA_CLIENT_ID)",
                "clientSecret": "$env(XAA_CLIENT_SECRET)"
              }
            },
            "resourceAs": {
              "tokenUrl": "https://auth.resource.xaa.dev/token",
              "audience": "https://auth.resource.xaa.dev",
              "resource": "https://mcp.xaa.dev/mcp",
              "clientAuth": {
                "method": "client_secret_post",
                "clientId": "$env(XAA_RESOURCE_AS_CLIENT_ID)",
                "clientSecret": "$env(XAA_RESOURCE_AS_CLIENT_SECRET)"
              }
            }
          }
        }
      }
    }
  ]
}

The IdP, resource authorization server, and upstream endpoints are wired to the playground here. Only the credentials and the gateway audience are environment-driven, so you can plug in your own xaa.dev app. For every option, see the configuration reference.

Next, add the route that exposes the gateway. Open config/routes.oas.json (the raw routes.oas.json tab) and replace its contents:

config/routes.oas.json
{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "XAA MCP Gateway",
    "description": "MCP gateway that bridges to the xaa.dev Todo0 MCP server via Cross App Access (ID-JAG)."
  },
  "paths": {
    "/mcp/todo0": {
      "post": {
        "operationId": "todo0Bridge",
        "summary": "Bridge to the xaa.dev Todo0 MCP server",
        "x-zuplo-route": {
          "corsPolicy": "none",
          "handler": {
            "module": "$import(@zuplo/runtime/mcp-gateway)",
            "export": "McpProxyHandler",
            "options": {
              "rewritePattern": "https://mcp.xaa.dev/mcp"
            }
          },
          "policies": {
            "inbound": ["xaa-inbound", "id-jag-upstream"]
          }
        }
      }
    }
  }
}

The McpProxyHandler forwards the request to the upstream Todo0 server, and both policies run inbound — first the MCP OAuth check, then the XAA exchange.

Finally, register the MCP Gateway plugin. In the file tree, right-click the modules folder, select New Runtime Extension, and replace the generated file's contents:

modules/zuplo.runtime.ts
import { RuntimeExtensions } from "@zuplo/runtime";
import { McpGatewayPlugin } from "@zuplo/runtime/mcp-gateway";

// Registers the MCP Gateway, which adds the OAuth and upstream-connection
// routes used to expose and secure MCP servers through your gateway.
// Docs: https://zuplo.com/docs/mcp-server/introduction
export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addPlugin(new McpGatewayPlugin());
}

Save each file. The build fails until the environment variables exist — that's the next step.

Set the environment variables.

Open Settings → Environment Variables and add each variable below with Add variable. Mark the two *_SECRET values as Secret so they're encrypted and hidden after saving. Leave all three environments (Production, Preview, Development) selected.

Saving an environment variable triggers a new deployment. Once it finishes, the gateway is live.

Connect with MCP Jam and list the todos.

Open the MCP Jam web inspector, go to Connect, and select Add Server:

• Server Name — xaa-quick-start
• Connection Type — HTTPS, with the route URL https://your-gateway.zuplo.dev/mcp/todo0
• Authentication — OAuth

Select Add Server. MCP Jam starts the OAuth flow and redirects you to sign in. Sign in at the IdenX screen (any email, no password) and approve the consent screen. MCP Jam returns to the inspector and the server shows as Connected.

Open the Resources panel and select List all todos. The todos come back as JSON — the agent never touched the XAA protocol. Behind the scenes the gateway minted an ID-JAG from the playground IdP, redeemed it at the resource authorization server, and called the Todo0 MCP server with the resulting access token.