← DtwoCONTENT HISTORY
WHAT CHANGED
Update to Dtwo
Snapshot Nov 16, 2026 · 18:15 UTC · version 1.3.5
Collection source: downloaded plugin package.
First saved snapshot
No earlier snapshot is available to establish a change.
Save Dtwo and check future changes in Following.
Up to 3 plugins free · no card required.
Compare saved observations
Download comparison JSONFull technical diff · 0 changed fields
Full snapshot data
{
"description": "Guide a first-time user through complete Dtwo gateway setup end to end — verify the Dtwo MCP connection,\nchoose a deployment type, create the gateway, configure authentication, add MCP servers, attach starter\npolicies, publish, activate (self-hosted), deploy, print ready-to-paste connection instructions, and\nfinish by authenticating to the gateway and testing the attached policies.\nTRIGGER when: user is setting up Dtwo for the first time, onboarding, just installed the plugin, or says\n\"set up dtwo\", \"create my first gateway\", \"get me started\", \"walk me through setup\".\nSKIP when: the user already has a gateway and wants a single focused change — editing gateway YAML or MCP\nserver entries (use dtwo-gateway-config); attaching/detaching or publishing policies (use dtwo-gateway-policy);\nwriting/modifying/explaining Rego (use dtwo-policy-rego); or producing a guide to send to their end users\nabout an existing gateway (use dtwo-end-user-guide).\n",
"included_files": [],
"name": "setup",
"skill_md_contents": "---\nname: \"setup\"\ndescription: |\n Guide a first-time user through complete Dtwo gateway setup end to end — verify the Dtwo MCP connection,\n choose a deployment type, create the gateway, configure authentication, add MCP servers, attach starter\n policies, publish, activate (self-hosted), deploy, print ready-to-paste connection instructions, and\n finish by authenticating to the gateway and testing the attached policies.\n TRIGGER when: user is setting up Dtwo for the first time, onboarding, just installed the plugin, or says\n \"set up dtwo\", \"create my first gateway\", \"get me started\", \"walk me through setup\".\n SKIP when: the user already has a gateway and wants a single focused change — editing gateway YAML or MCP\n server entries (use dtwo-gateway-config); attaching/detaching or publishing policies (use dtwo-gateway-policy);\n writing/modifying/explaining Rego (use dtwo-policy-rego); or producing a guide to send to their end users\n about an existing gateway (use dtwo-end-user-guide).\n---\n\n<!-- © 2026 Dtwo, Inc. -->\n\n# Dtwo Guided Setup\n\nYou help a first-time user stand up their first Dtwo MCP gateway from nothing, conversationally and end to end. This skill is the orchestrator: it drives the whole first-run journey and hands off the detail work — YAML edits, policy authoring, Rego — to the companion skills at the right moments. Keep the tone friendly and plain, explain the *why* before each step, and confirm before anything that changes live state (publish, activate, deploy).\n\n## Overview to give the user first\n\nBefore Phase 1, orient the user with a short, plain-language overview — this is their first impression of the whole journey, so keep it succinct. A sentence or two on what Dtwo actually is, a sentence or two on what you'll do together, plus the list below, is enough. Don't read the 12-phase list aloud; that level of detail belongs in the phases themselves, not the intro.\n\nKeep the two ideas — what Dtwo *is* and what you'll *do together* — visually distinct rather than one run-on paragraph: a short line on the what, a blank line, then the plan. Word the plan sentence to mirror the six steps in the same order (create, configure, add, add, connect, test), so the prose and the list tell the same story instead of drifting into different phrasing. Say something close to (adapt naturally, don't recite verbatim):\n\n> Dtwo is a gateway that sits between your AI client and the systems it talks to — every tool call passes through it, so policy can be applied before anything reaches your real systems.\n>\n> I'll get a working gateway running end to end: create your gateway, configure who's allowed to connect, add the MCP servers it'll front, add some policies so it actually enforces something, connect your AI client once it's live, and test that the policies actually work. I'll check in with you at each decision point, and you can pause and pick back up anytime.\n\nThen show the six stages as a compact list (each stage bundles several phases — don't list all 12 individually, it's too much for a first look). Use this plain-text form, in a fenced code block, whatever host you are running in:\n\n```\n1. Create your gateway\n2. Configure auth\n3. Add MCP servers\n4. Add policies\n5. Connect AI client\n6. Test policies\n```\n\nOnly expand into more detail (naming every phase, tool names, YAML) if the user asks for it up front — the point of this overview is a quick sense of the shape of the journey, not a full table of contents.\n\n## Showing progress\n\nThere are **six separate checkpoints** below, one per stage. This is not something you do once and stop — every one of the six needs its own redraw when its phase completes, all the way through Phase 12. Each phase that ends in a checkpoint repeats this instruction with a running count (\"checkpoint N of 6\") specifically so it isn't dropped partway through a long setup — treat skipping any of them as a bug.\n\nRedraw the six-step list from the overview at each checkpoint, so the user can see how far they've gotten. Same plain-text form as the overview, with a checkmark (`✅ `) in front of each finished step and the rest left as they are.\n\nShow it once per checkpoint, right after the phase work that completes it — don't hold everything back and redraw retroactively at the end.\n\nCheckpoints:\n\n- After **Phase 3** (gateway created) → check off **Create your gateway**.\n- After **Phase 4** (authentication configured) → also check off **Configure auth**.\n- After **Phase 5** (MCP servers saved) → also check off **Add MCP servers**.\n- After **Phase 10** (deploy completes) → also check off **Add policies** (this step bundles Phases 6–10: choosing/creating policies, attaching them, publishing, activating, and deploying).\n- After **Phase 11** (client connection registered) → also check off **Connect AI client**.\n- After **Phase 12**, resolve **Test policies**: if the policy test ran and confirmed enforcement, check it off — all six are now checked, so say something short marking setup as complete instead of describing what's next. If policies were skipped back in Phase 6, leave **Test policies** unchecked (or mark it \"skipped\") instead — but still say that same short setup-complete close so the user isn't stranded at 5/6 with no closing moment, and repeat the pass-through reminder that nothing is enforced until a policy is attached.\n\nExample, with the first three steps done:\n\n```\n1. ✅ Create your gateway\n2. ✅ Configure auth\n3. ✅ Add MCP servers\n4. Add policies\n5. Connect AI client\n6. Test policies\n```\n\nKeep the redraw brief: the list itself plus one short line about what's next (or, on the last checkpoint, that setup is complete) — don't re-explain steps already covered in the overview.\n\n## Communicating with the user\n\nPhase numbers, tool names, and schema fields (`dtwo-create-gateway`, `jwt_jwks_uri`, `deploymentType: hostedAws`, and so on) are your internal organizing structure — they are not vocabulary for talking to the user. Do the right technical steps behind the scenes; describe them in plain, outcome-focused language throughout all 12 phases, not just the opening overview.\n\n- **Don't narrate internal mechanics.** Never say \"I'll call `dtwo-create-gateway`\" or \"moving to Phase 5 now.\" Say what's happening and why it matters: \"Now I'll create your gateway\" or \"Next, let's decide who's allowed to connect.\"\n- **Translate protocol jargon into the plain choices already written into each phase.** The one-line descriptions in Phase 2 (hosted vs. local vs. self-hosted) and Phase 4 (Dtwo-managed sign-in vs. your own identity provider) are the right register — lead with those, not the raw enum values (`hostedAws`, `dtwo_default`, etc.). If you need specific fields from a custom identity provider (JWKS URL, issuer, audience), ask for them in the provider's own terms (\"the JWKS URL your identity provider publishes\"), not as bare field names.\n- **Frame activation and connection steps around what the user is doing, not the artifact names.** \"Here's a small config file to start the gateway on your machine, an activation file so Dtwo recognizes it, and the commands to run\" reads better than leading with `composeFileName` / `dtwo.env`. The copyable code blocks themselves are necessary and fine to show — just introduce them in plain language first.\n- **Keep deploy/status updates outcome-level.** \"Deploying now, this usually takes under a minute\" beats describing task UIDs, polling loops, or transient error codes (502s during a restart) — surface those only if something is actually stuck and the user needs to know why.\n- **Phase numbers are for your bookkeeping, not required conversation.** It's fine to reference \"step\" or \"the next part\" loosely, or to name a phase when resuming a partial setup so the user can orient (\"looks like MCP servers are set up but no policies yet\") — but don't recite \"Phase 6\" as a matter of routine.\n- **Surface technical detail on request, not by default.** If the user asks what auth type was used or wants to see the YAML, give the precise answer. Default conversation stays plain; go deeper only when asked or when a real decision hinges on a distinction they need to understand to choose correctly.\n- **Exception: technical users.** If the user is already using precise technical vocabulary (tool names, field names, protocol terms), mirror their register — this guidance protects non-technical users from unnecessary jargon, it isn't meant to dumb down conversations with engineers who want the detail.\n\n## Where things are in the Dtwo Hub\n\nA few steps below can only be done in the Dtwo Hub, the web app, and the phases that send the user there\nsay so. Naming a page or a field is not enough on its own: say where on the screen to look, so the user can\nfollow the directions without hunting for them. The layout, so you can describe it accurately:\n\n- **Left sidebar**, three items top to bottom: **Dashboard**, **Gateways**, **Policies**. It collapses to\n icons; the toggle for that sits at the top left of the page, just left of the breadcrumbs.\n- **The account menu** is at the very bottom of that left sidebar, on the user's own name. **Setup guide**\n is in it, and that is the Hub's own version of this setup.\n- **A gateway's page**: click **Gateways** in the left sidebar, then the gateway's name in the list. Its\n tabs run across the top of the page, in the middle: **Overview**, **Configuration**, **Policies**,\n **Deployments**. A gateway that hasn't checked in yet shows **Registration** in place of Overview.\n- **Gateway URL** and **Callback URL** are on the **Configuration** tab, inside the **Authentication**\n panel at the top of it. That panel is collapsed on a gateway that already has connection details, so it\n may need opening first (the caret on its right-hand side). Both fields are only editable on a self-hosted\n gateway, since Dtwo assigns the URL for the hosted and local types.\n- **Deploy**, **publish a version**, **version history**, and **delete** are behind the **⋯** button at the\n top right of a gateway's page.\n- **Policies** in the left sidebar lists every policy in the organization. The ones attached to one\n particular gateway are on that gateway's **Policies** tab.\n\nWrite a click path the way the user walks it, naming the region at each hop: \"In the left sidebar, click\n**Gateways** and open your gateway. On the **Configuration** tab, the **Authentication** panel at the top\nholds **Gateway URL**.\" An arrow chain of bare names (Hub → Gateways → Configuration) leaves out the part\nthat actually helps.\n\n## Companion skills\n\nThis skill orchestrates the others. Invoke them via the `Skill` tool when a phase calls for their detail work (in other agents, use your host's equivalent skill-loading mechanism):\n\n- **dtwo-gateway-config** — load for the MCP-servers phase (editing the draft config's `mcp_servers`, validating, saving) and any deeper config/auth questions. It owns the gateway YAML schema; don't duplicate that schema here.\n- **dtwo-gateway-policy** — load for the policies and pipeline-attachment phases (creating/importing policies, `dtwo-set-gateway-pipelines`, publish/pin semantics).\n- **dtwo-policy-rego** — load (usually via `dtwo-gateway-policy`) when the user wants to author a custom starter policy rather than import one from the catalog.\n\n## Prerequisites\n\nThis skill requires the Dtwo MCP server to be connected (`dtwo-*` tools must be loaded). If the tools are not available, ask the user to install and enable the Dtwo plugin (or connect the Dtwo MCP server) first, then restart the session. Judge that by whether the tools are in your tool list, never by whether a call succeeded: a call that fails on a server that is connected is a different thing, and Phase 1 covers it.\n\nThe tools listed below reflect the current set. The Dtwo MCP server may add new tools over time — if you discover `dtwo-*` tools not listed here, use them where appropriate. Prefer newer, more specific tools over workarounds when available. If a setup-specific tool named below is **not** present on the connected server, see **Graceful degradation** at the end — the server may not support plugin-driven setup yet.\n\n**Tool naming note:** This skill refers to the Dtwo MCP tools by their short names (e.g., `dtwo-list-gateways`, `dtwo-create-gateway`). In Claude Code, that short name is what you call directly — the `mcp__dtwo__` server prefix is stripped automatically. In other MCP clients you may see the fully-qualified name `mcp__dtwo__dtwo-list-gateways`; both refer to the same tool.\n\n## Tools this skill uses\n\nSetup-specific tools (may be newer — see Graceful degradation if any are missing):\n\n| Tool | Purpose |\n|------|---------|\n| `dtwo-create-gateway` | Create a draft gateway with an empty config. Input `{ name, tags?, deploymentType?, allowAdditionalHosted? }` where `deploymentType` is `hostedAws` \\| `standard` \\| `localHttp`. For `hostedAws` it also queues AWS provisioning. `localHttp` and `hostedAws` gateways get a platform-assigned URL, so they are created with the Dtwo-managed Auth0 IdP already bound to it; a `standard` gateway is created with neither a URL nor authentication. First-run guardrail: creating a hosted gateway when one already exists errors with guidance naming the existing one, unless you pass `allowAdditionalHosted: true` to confirm you want another |\n| `dtwo-set-gateway-auth` | Deterministically write the `gateway.authentication` block into the draft config. Input `{ uid, mode, customFields? }` where `mode` is `dtwo_default` \\| `custom` \\| `disabled` \\| `removed`. `dtwo_default` uses the Dtwo-managed Auth0 IdP and needs no IdP details from the user; it binds to the gateway's own URL as the token audience, so it works on any deployment type once the gateway has a URL, and errors when it doesn't. `custom` takes the audience from `customFields` and so needs no gateway URL. On `localHttp` and `hostedAws`, which are created on the Dtwo-managed IdP already, this tool is for moving off that default rather than first-time setup. `customFields` carries `jwt_algorithm`, `jwt_jwks_uri`, `jwt_issuer`, `jwt_audience`, `sso_issuer` when `mode: custom` |\n| `dtwo-update-gateway` | Update gateway metadata. Input `{ uid, name?, tags?, url?, callbackUrl? }`. This is how a `standard` gateway gets the MCP URL it was created without. The URL is the audience the Dtwo-managed IdP binds to, so it has to be set before `dtwo-set-gateway-auth` with `mode: dtwo_default`; `mode: custom` carries its own audience and doesn't need it. Either way it can be left for a later session if the user doesn't have the address yet. `url` and `callbackUrl` are `standard`-only, since `localHttp` and `hostedAws` URLs are platform-assigned and a change to those is refused |\n| `dtwo-get-gateway-connection-info` | Fetch client connection details, on any deployment type. Input `{ uid }` → `{ mcpUrl, authMode, clientId?, audience?, issuer?, jwksUri?, domain?, callbackPort? }`. `authMode` tells you how much is filled in: `dtwo` carries the audience, issuer, JWKS URI, Auth0 domain, and the tenant's client id when it has one; `custom` carries the audience, issuer, and JWKS URI the gateway verifies against, and no client id; `none` means auth is off, so the URL is all there is; `unknown` means the saved config couldn't be read. `callbackPort` (33418) comes back for `custom` only, on any deployment type. Errors when the gateway has no URL yet, which for `standard` means the `dtwo-update-gateway` step hasn't happened |\n| `dtwo-create-gateway-activation` | Create (mint) the **first-run** activation bundle for a **self-hosted** gateway. Input `{ uid }` → `{ activationId, activationCode, activationExpiresAt, composeText, composeFileName, activationCommand, minted }`. Every call mints a fresh pair and returns `minted: true`, invalidating any previously issued one; the pair is single-use and lasts 24 hours. Call it once per activation attempt. Use `activationId` and `activationCode` to write the `dtwo.env` file described in Phase 9 rather than running `activationCommand`, which still returns an older `.env`-writing form. `composeText` carries the `443:443`→`80:80` port swap for `localHttp`. Errors for `hostedAws` (nothing to activate, since provisioning is managed) |\n| `dtwo-refresh-gateway-activation` | Mint a fresh activation pair for a `localHttp` or `standard` gateway that is already up, invalidating any previously issued one. Input `{ uid }` → the same fields as `dtwo-create-gateway-activation`. Again, take `activationId` and `activationCode` and rewrite `dtwo.env`; its `activationCommand` is an older `docker compose down` / `.env` form. Re-register with `docker compose --env-file dtwo.env up -d --force-recreate`, which recreates the container on the image it already has. For a host that has never come up, use `dtwo-create-gateway-activation` instead, since its flow pulls the image. Errors for `hostedAws`: refreshing would invalidate the credential the provisioning instance is using |\n| `dtwo-record-setup-progress` | Record the closing setup steps on the account, so the Dtwo Hub shows setup as finished instead of asking the user to confirm work you already did with them. Input `{ steps }`, any of `connectClient` \\| `testPolicies` \\| `plugin`. Steps merge with anything already recorded, so call it as each one lands rather than all at the end. Only these three are accepted; everything earlier (gateway, MCP servers, policies, deploy) the platform reads from the account itself |\n| `dtwo-get-setup-progress` | Read back which closing steps are already recorded. Input `{}` → `{ completedSetupSteps, completedAssertedSteps }`. Useful when resuming an interrupted setup |\n\nExisting lifecycle tools this skill leans on (documented in the companion skills):\n\n| Tool | Purpose |\n|------|---------|\n| `dtwo-list-gateways` / `dtwo-get-gateway` | Discover existing gateways; check provisioning/heartbeat state |\n| `dtwo-get-gateway-config` / `dtwo-save-gateway-draft-config` / `dtwo-validate-gateway-config` | Read, validate, and save the draft config (MCP servers) — via `dtwo-gateway-config` |\n| `dtwo-list-vault-entries` / `dtwo-get-vault-secret-link` | Find an existing Vault entry, or get the Hub link where the user enters an upstream server's credential — via `dtwo-gateway-config` |\n| `dtwo-list-catalog-policies` / `dtwo-get-catalog-policy-filters` / `dtwo-import-catalog-policy` | Browse and import starter policies from the policy catalog |\n| `dtwo-add-policy` / `dtwo-publish-policy` | Create/publish a custom policy — via `dtwo-gateway-policy` + `dtwo-policy-rego` |\n| `dtwo-set-gateway-pipelines` / `dtwo-get-gateway-pipelines` | Attach imported/created policies to the ingress/egress pipelines — via `dtwo-gateway-policy` |\n| `dtwo-publish-gateway-config` | Publish the draft config as a version |\n| `dtwo-deploy-gateway` / `dtwo-get-deployment` / `dtwo-get-gateway-deployments` | Deploy and poll deployment status |\n\n## How to run this\n\nGive the **Overview to give the user first** above before doing anything else. Then work through the phases below in order. Before starting, if your host supports `AskUserQuestion`, use it for the multiple-choice decision points (deployment type, auth mode, policy approach); otherwise ask in plain language. Never guess a UID — always carry forward the `uid` returned by `dtwo-create-gateway`. Confirm with the user before any live-state change: publishing config, activating, and deploying.\n\nIf the user is returning to a half-finished setup, jump to **Resuming a partial setup** first to figure out where to pick up (skip the overview in that case — they've already seen it).\n\n---\n\n### Host-specific behavior\n\nUse the current host's tools and skill-loading mechanism. In Cursor, load companion skills from the shared `skills/` directory if the host has no skill-loading tool. Do not require Claude's `Skill`, `/mcp`, `/reload-plugins`, or `/dtwo:setup` commands in Cursor. A natural-language request to use the Dtwo setup skill starts this flow.\n\nWhen connecting the gateway in Phase 11, choose the current host's instructions first. Shell access in Cursor does not mean Claude Code is installed. In Cursor, merge the new server entry into `~/.cursor/mcp.json` or the project's `.cursor/mcp.json`, preserving all other servers. Ask before editing that file. Use the gateway connection tool's `clientId`, not the management plugin's client ID. If authentication is enabled and that ID is missing, obtain the registered ID before proceeding; never guess one or attempt dynamic client registration.\n\nCursor desktop uses `http://localhost:8787/callback`. The authorization server must allow that exact URI for the static client. Do not use Claude's `oauth.callbackPort` or ask for a new port on each login. Enable the server in Cursor's Customize panel, complete sign-in, and verify a tool call. After a connection change, reload the window if the tools have not appeared. Web/Agents authentication is outside these instructions.\n\n### Phase 1 — Verify the connection\n\nCall `dtwo-list-gateways`.\n\n- **First-call OAuth.** The very first `dtwo-*` call in a session triggers a browser OAuth flow. Tell the user plainly: \"A browser window will open so you can sign in to Dtwo — complete that and I'll continue.\"\n- **A failed first call is not a disconnected server.** The first call of a session is the one most likely to come back with an error, and none of the usual ones mean the plugin is unavailable: sign-in may not be finished yet, or the client may still be holding a session the server has since dropped (`Bad Request: No valid session ID provided`, or a bare 400 or 401). Say you're retrying and call the same tool again. A second attempt normally succeeds, because the client opens a fresh session on its own. Go to **Graceful degradation** only when no `dtwo-*` tool is in your tool list at all — check the fully-qualified `mcp__dtwo__…` form too, since that is how some clients name them. A tool that exists and returns an error is a connected server reporting a problem, not a missing one.\n- **Never tell the user to switch AI clients.** This skill does the same work in every host it runs in, and nothing that fails here is fixed by moving to Claude Code, Claude Desktop, or anything else. When something really is unavailable, the fallback is the Hub's guided setup (see **Graceful degradation**), never a different client.\n- **No gateways yet** → this is a genuine first-time setup. Continue to Phase 2.\n- **Gateways already exist** → ask whether they want to (a) set up a brand-new gateway anyway, or (b) switch to managing an existing one. If (b), hand off to the companion skills (`dtwo-gateway-config` for config, `dtwo-gateway-policy` for policies) and stop here. If they aren't sure, briefly list the existing gateways by name and let them choose.\n\n### Phase 2 — Choose a deployment type and name\n\nShow this table in your message, unmodified, before asking anything — this is the guaranteed way the user actually sees the descriptions, regardless of whether your host renders per-option descriptions on a multiple-choice widget:\n\n| Deployment type | Description |\n|---|---|\n| Dtwo hosted | Dtwo runs the gateway for you in the cloud. Zero local infrastructure. |\n| Local | Runs on your machine via Docker, serving plain HTTP on port 80. This is not meant for production. |\n| Self-hosted | You self-host on your own infrastructure over HTTPS. Most control, most setup. |\n\nMap the user's choice to `deploymentType`: Dtwo hosted → `hostedAws`, Local → `localHttp`, Self-hosted → `standard`. You'll pass this value to `dtwo-create-gateway` in Phase 3.\n\nSay that the deployment type can't be changed after the gateway is created, since this is the one choice in the whole setup that a later session can't revise: switching means creating a new gateway. Everything else here (auth, MCP servers, policies, the URL on a self-hosted gateway) can be changed later.\n\nSelf-hosted is the one type where Dtwo can't work out the gateway's address for itself, so a self-hosted gateway needs the public HTTPS URL clients will call. If that's what the user picks, mention it now rather than surprising them with the question later. They can give it in Phase 3 if they know it, or leave it blank and come back once DNS, a load balancer, or a certificate is in place: Dtwo-managed sign-in and the connection step are the only parts that wait on it.\n\nThen ask which they want:\n\n- If your host supports `AskUserQuestion`, still populate each option's `description` field verbatim from the table (some hosts do render it, and it costs nothing to include), but never rely on it alone — the table above is what actually guarantees the user sees the description. Match this shape exactly; labels and descriptions come verbatim from the table above:\n\n ```json\n {\n \"questions\": [{\n \"question\": \"Which deployment type do you want?\",\n \"header\": \"Deployment\",\n \"multiSelect\": false,\n \"options\": [\n { \"label\": \"Dtwo hosted\", \"description\": \"Dtwo runs the gateway for you in the cloud. Zero local infrastructure.\" },\n { \"label\": \"Local\", \"description\": \"Runs on your machine via Docker, serving plain HTTP on port 80. This is not meant for production use.\" },\n { \"label\": \"Self-hosted\", \"description\": \"You self-host on your own infrastructure over HTTPS. Most control, most setup.\" }\n ]\n }]\n }\n ```\n\n- If `AskUserQuestion` isn't available at all, just ask in plain language which one they want — the table above already carries the descriptions, so there's no need to repeat them in the question itself.\n\nThen ask for a **gateway name** (short and memorable). Optionally ask for tags.\n\n### Phase 3 — Create the gateway\n\nCall `dtwo-create-gateway` with `{ name, tags?, deploymentType }`. Capture the returned `uid` — you'll carry it through every later phase.\n\n- For **hostedAws**, creation also queues AWS provisioning; note that so the user knows something is happening in the background.\n- **Hosted-already-exists guardrail.** If `deploymentType: hostedAws` fails because a hosted gateway already exists, the error names the existing one. Tell the user plainly and offer three options: (a) reuse the existing hosted gateway (switch to managing it via the companion skills, or continue this flow against its `uid`), (b) create a `localHttp` or `standard` gateway instead, or (c) confirm they really do want an additional hosted gateway, in which case re-run `dtwo-create-gateway` with `allowAdditionalHosted: true`. Re-run with their choice.\n\n- **Hosted not enabled for this organization.** Creation can also fail with a message about an `orgName` being required for a hosted gateway in AWS. That means the organization isn't set up for Dtwo-hosted gateways yet, not that anything is wrong with the request. Say so plainly, tell the user to contact Dtwo to have it enabled, and offer a `localHttp` or `standard` gateway meanwhile.\n\n**Set the gateway URL (`standard` only).** A `standard` gateway is created with no URL and no authentication, because its address is something only the user knows. Ask for the public URL MCP clients will call, then set it with `dtwo-update-gateway` `{ uid, url }`.\n\nLeaving it blank is a normal way through this setup, not a mistake to argue the user out of. Someone still standing up DNS, a load balancer, or a TLS certificate may not have the address for hours or days, and everything else (MCP servers, policies, the rest of the config) can be built out meanwhile. If they don't have it yet, say what's waiting on it and move on: the URL is the token audience the Dtwo-managed identity provider binds to, so that option can't be configured without it, and Phase 11 has no endpoint to hand a client. Their own identity provider can still be configured now, since they supply the audience themselves. Tell them they can pick this setup back up any time, or set the address themselves in the Hub: **Gateways** in the left sidebar, then their gateway, then the **Gateway URL** field in the **Authentication** panel at the top of the **Configuration** tab. Either way, authentication is the step to return to once it's set.\n\nWhen they do have the URL, say what shape it takes, with an example: `https://gateway.example.com/mcp`. What the platform accepts:\n\n- **HTTPS**, absolute, including the scheme. Plain `http` is only allowed for loopback addresses.\n- **No query string, fragment, or embedded credentials.** The URL is compared exactly when a token is validated, so anything that varies per request can't be part of it.\n- It has to be the address clients actually reach, not an internal or container-local one. Everything downstream (the audience, the OAuth callback, the instructions in Phase 11) is derived from it.\n\nThree errors are worth recognizing so you can explain them rather than just relaying them:\n\n- **URL rejected as invalid** → the message names the reason (missing scheme, a query string, and so on). Ask for a corrected URL and call again.\n- **URL already registered with the identity provider** → another gateway is using it. Ask for a different one.\n- **Changing a URL that authentication is already bound to** → this isn't an error, but tell the user before doing it. The URL is the token audience, so changing it on a gateway already on the Dtwo-managed IdP re-registers its identity-provider API, and tokens minted for the old URL stop working: everyone reconnects. Setting a URL for the first time has no such cost.\n- **`url` rejected as an unknown input** → the connected Dtwo environment predates self-hosted URL support on the MCP surface. Don't try to work around it. Tell the user their gateway needs its **Gateway URL** field filled in from the Hub: **Gateways** in the left sidebar, then their gateway, then the field of that name in the **Authentication** panel at the top of the **Configuration** tab. Continue from Phase 4 once they confirm it's saved.\n\n**Callback URL.** Sign-in returns to `<gateway-url-without-/mcp>/oauth/callback` by default, so `https://gateway.example.com/mcp` gives `https://gateway.example.com/oauth/callback`. Self-hosted deployments often don't land there: a proxy, an ingress, or a separate auth host in front of the gateway can all put the redirect somewhere else, so expect this to differ more often than not. Ask the user where their OAuth redirect terminates, offer the default as the answer when it's right, and pass `callbackUrl` when it isn't.\n\n**Show progress — checkpoint 1 of 6, do this now.** Redraw the six-step list with only **Create your gateway** checked off. Five more checkpoints still need their own redraw later: Configure auth (Phase 4), Add MCP servers (Phase 5), Add policies (Phase 10), Connect AI client (Phase 11), Test policies (Phase 12) — don't stop doing this after this first one.\n\n### Phase 4 — Authentication\n\nAuthentication controls who may connect to the gateway.\n\n**If a `standard` gateway has no URL yet**, only the Dtwo-managed option waits on it: that one binds to the gateway's own URL as the token audience, so there's no audience to bind to until the URL is set. Their own identity provider doesn't wait, because they supply the audience themselves: if the user already has a JWKS URL, issuer, audience, and algorithm, configure `mode: custom` now and the URL becomes a Phase 11 question instead of a Phase 4 one.\n\nIf neither is possible yet, tell the user authentication is parked, leave it un-configured, carry on with Phase 5, and come back here once they have the address. Be straight with them about what parked means, because nothing downstream will stop them: a config with no `gateway.authentication` block validates cleanly and deploys with client authentication off, so a gateway deployed in that state is open to anyone who can reach its URL. Phases 8 and 10 repeat this warning at the two points where it starts to matter.\n\n**A `localHttp` or `hostedAws` gateway is already authenticated when it reaches this phase.** Dtwo assigns those URLs, so both types are created with the Dtwo-managed IdP already bound to that audience. Still ask the question, since the user should know which IdP their gateway is on and get the chance to change it, but describe it as confirming what's already set rather than as configuring auth from scratch. Choosing Dtwo-managed re-applies the same defaults, which is a no-op, and it's fine to say so. Choosing their own IdP moves the gateway off a working default onto one they have to maintain, so say that too and let them decide.\n\nBoth options below are available on **every** deployment type, self-hosted included, so ask the same question regardless of what the user picked in Phase 2. Don't apply the recommended default without asking. Show this table in your message before asking, for the same reason as Phase 2: it's the guaranteed way the user sees the descriptions, regardless of whether your host renders per-option descriptions on a multiple-choice widget:\n\n| Auth method | Description |\n|---|---|\n| Dtwo-managed sign-in (recommended) | The Dtwo-managed Auth0 IdP validates incoming tokens with no IdP setup on your side. |\n| Your own identity provider | Collect your JWKS URL, issuer, audience, and algorithm, and the gateway validates against your IdP instead. |\n\nThen ask which one — still populate `AskUserQuestion` option descriptions from this table if your host supports it, but the table above is what actually guarantees the description is shown, not the widget field. Once they answer, call `dtwo-set-gateway-auth`: `mode: dtwo_default` for the recommended sign-in, or `mode: custom` for their own identity provider, collecting `jwt_algorithm`, `jwt_jwks_uri`, `jwt_issuer`, `jwt_audience`, and `sso_issuer` into `customFields`. All five are required when `mode: custom`, so gather them before calling rather than sending a partial block.\n\n**On `mode: dtwo_default`.** This is the recommended default on every deployment type, `standard` included: the block binds to the gateway's own URL as the token audience, so a self-hosted gateway on the Dtwo-managed IdP needs no IdP setup either. If the call errors saying the gateway has no URL to bind to, the URL isn't set yet: either set it with `dtwo-update-gateway` and call this again, or leave authentication for later if the user still doesn't have the address.\n\n**On `mode: custom`.** For anything beyond the five fields collected above, defer to the **dtwo-gateway-config** skill's authentication section (the `jwks_info` block) rather than duplicating schema docs here. Load that skill if the user needs the full picture. Two things to tell the user, because they're work on their side that the gateway can't do for them:\n\n- **Register the gateway's OAuth callback with their IdP.** Sign-in returns to the gateway's callback URL (whatever `callbackUrl` was set to in Phase 3, or `<gateway-url-without-/mcp>/oauth/callback` if it was left at the default), and their IdP will refuse the flow until that exact URL is in its allowed redirect list. This is the most common reason a custom-IdP gateway comes up and then fails to authenticate.\n- **`jwt_audience` should be the gateway's own URL**, unless they have a reason for it to differ. A mismatch here means tokens their IdP issues are rejected by the gateway. Check it against the `url` on `dtwo-get-gateway`, not against `dtwo-get-gateway-connection-info`: under `authMode: custom` that tool reads the audience back out of the saved config, so it echoes whatever was just written and can never disagree with it.\n- **`sso_issuer` is normally the same value as `jwt_issuer`.** It's the issuer advertised to clients for OAuth discovery, while `jwt_issuer` is the one the gateway validates tokens against, so a different value means clients are sent to one authorization server while the gateway only accepts tokens from another. Offer the issuer they already gave as the answer, and ask before writing anything else.\n\nYou don't need to do anything for client discovery: supplying `sso_issuer` turns on RFC 9728 resource metadata automatically, which is what lets spec-compliant MCP clients find the IdP from the gateway URL alone.\n\n**Show progress — checkpoint 2 of 6, do this now.** Redraw the list with **Create your gateway** and **Configure auth** both checked off. If authentication is parked waiting on a URL, leave **Configure auth** unchecked and say what it's waiting for. Still to come: Add MCP servers (Phase 5), Add policies (Phase 10), Connect AI client (Phase 11), Test policies (Phase 12).\n\n### Phase 5 — Add MCP servers\n\nMCP servers are the tools the gateway fronts. Start with the fastest path, then offer custom servers.\n\n**Quick start (recommended first).** Offer this curated list of zero-config remote MCP servers. They work anonymously over streamable HTTP, so they need no setup on your side and are the quickest way to see the gateway working. Frame them honestly: they exist to get started with Dtwo fast, and for real gateway usage the user is free to put whatever MCP servers they need behind the gateway (see Custom servers below). Present them as a pick-list (use `AskUserQuestion` with multi-select where available; otherwise ask in plain language which the user wants, allowing several):\n\n| Server | What it does | URL |\n|---|---|---|\n| Context7 | Up-to-date code documentation and examples for popular libraries | `https://mcp.context7.com/mcp` |\n| DeepWiki | Ask questions about any public GitHub repository | `https://mcp.deepwiki.com/mcp` |\n| Microsoft Learn | Official Microsoft and Azure documentation | `https://learn.microsoft.com/api/mcp` |\n| Hugging Face | Search models, datasets, and Spaces on the Hub | `https://huggingface.co/mcp` |\n| Cloudflare Docs | Search Cloudflare's developer documentation | `https://docs.mcp.cloudflare.com/mcp` |\n| GitMCP | Turn any GitHub repository into a documentation source | `https://gitmcp.io/docs` |\n\nFor each one the user picks, add an `mcp_servers` entry with just three fields: `name`, `url` (the table URL), and `transport_type: streamable_http` (the value the Dtwo Hub writes for these same servers; the schema also accepts `streamablehttp`, `http`, and `sse`, and the underscore form and the one-word form reach the gateway identically). Do not add an `authentication` block at all. These are public, anonymous servers, so they need no authentication, and leaving the block off is deliberate: writing `authentication: type: none` tells the gateway to forward your access token to the upstream, which public servers reject and which needlessly exposes your token. Omitting authentication is optional in the schema and validates cleanly. Use a kebab-cased id as the entry `name` (`context7`, `deepwiki`, `microsoft-learn`, `hugging-face`, `cloudflare-docs`, `gitmcp`), matching the Dtwo Hub.\n\n**Custom servers (anything else).** Any MCP server can go behind the gateway; this is the normal path for real usage. Start with Dtwo's setup guide for the server: fetch `https://docs.dtwo.ai/llms.txt` and match the server or vendor the user named against the guide titles and descriptions. When there's a guide, take the URL, transport, and authentication settings from its YAML entry, and give the user its web page (the link without `.md`) for the steps on the vendor's side, along with the gateway's actual callback URL to register there (Phase 3 covers what it is) rather than the guide's placeholder. When there isn't one, give them `https://docs.dtwo.ai/docs/mcp-server-custom`, the guide for any MCP server, and collect the URL and transport from them. If you can't fetch web pages, give them the guide index, `https://docs.dtwo.ai/docs/mcp-servers`, instead of guessing a guide's address. The **dtwo-gateway-config** skill has the full lookup.\n\nWhen the upstream needs credentials, add an `authentication` block; the **dtwo-gateway-config** skill owns the supported types (bearer token, basic, custom headers, query parameter, OAuth, certificate) and how to author them, including how credentials go in. The short version: the config holds a Vault reference such as `<<GITHUB_TOKEN>>`, and the user types the credential itself into the Dtwo Hub through a link you give them, never into the chat. A guide's entry follows the same rule: its `\"<CLIENT_SECRET>\"`-style placeholders become Vault references and never go into a saved config as text. Tell them the gateway can't deploy until that value is saved. For a public or no-auth upstream, omit the block entirely, the same as the quick-start entries above. One caveat to state plainly: many servers need setup on the vendor's side (an OAuth app, an API token, workspace approval) before the gateway can reach them, so they take a few more steps than the quick-start list. The server's guide covers that part.\n\nOffer to add more than one server, from either group. Load the **dtwo-gateway-config** skill and follow its flow to edit `mcp_servers`, then `dtwo-save-gateway-draft-config` + `dtwo-validate-gateway-config`. Do not restate the config schema here, that skill owns it (including transport type, outbound auth variants, and Vault references for credentials). If the user has no server in mind yet, it's fine to save an empty `mcp_servers` and add one later, but tell them the gateway won't front anything until a server is added.\n\n**Show progress — checkpoint 3 of 6, do this now.** Redraw the list with **Create your gateway**, **Configure auth**, and **Add MCP servers** checked off. Still to come: Add policies (Phase 10), Connect AI client (Phase 11), Test policies (Phase 12).\n\n### Phase 6 — Policies\n\nPolicies are what make the gateway *enforce* something rather than just proxy. Ask which approach they want:\n\n- **Import recommended starter policies** — call `dtwo-list-catalog-policies` with `{ tags: [\"onboarding\"] }`. That tag is what marks a catalog policy as a starter, and it's the same set the Dtwo Hub's guided setup offers, so there's no need to go discover it with `dtwo-get-catalog-policy-filters` first (use that tool if the user wants to browse the catalog by app, industry, or bundle instead). Show the user a short list, then `dtwo-import-catalog-policy` the ones they pick, passing the `policySource` each one came back with. This is the fastest safe start.\n- **Author a custom policy** — hand off to **dtwo-gateway-policy** (which pulls in **dtwo-policy-rego** for the Rego) and create it with `dtwo-add-policy`.\n- **Skip for now** — allowed, but warn plainly: with no policies attached, the gateway enforces nothing and every tool call passes through. They can add policies later with the companion skills.\n\nCapture the `uid` of every imported or created policy for the next phase.\n\n### Phase 7 — Attach policies to pipelines\n\nAttach the imported/created policy UIDs to the gateway's ingress/egress pipelines with `dtwo-set-gateway-pipelines`, following **dtwo-gateway-policy** semantics (draft vs. published, version pinning, step ordering). If a policy must be published before it can be pinned, follow that skill's publish-then-pin flow. Skip this phase if the user skipped policies in Phase 6.\n\n### Phase 8 — Publish the config\n\nConfirm with the user, then call `dtwo-publish-gateway-config` to publish the draft as a version. This freezes the config the deploy will use; it is not yet live on a running gateway.\n\n**If authentication was parked in Phase 4, say so before publishing.** Validation won't flag it (with no `gateway.authentication` block there's nothing to check), so this warning has to come from you. Tell the user plainly: this version has client authentication off, and once it's deployed anyone who can reach the gateway's URL can use it. Publishing on its own is harmless, since nothing is live yet, so it's fine to go ahead; the decision that matters is Phase 10.\n\n### Phase 9 — Activate (self-hosted only)\n\n**Skip this phase entirely for `hostedAws`** — there is nothing to activate; provisioning was queued at creation. Instead, check `dtwo-get-gateway` (and `dtwo-get-gateway-deployments` if useful) to confirm provisioning has progressed before deploying in Phase 10.\n\nFor **localHttp / standard**, call `dtwo-create-gateway-activation` `{ uid }` to mint an activation and get `{ activationId, activationCode, activationExpiresAt, composeText, composeFileName, activationCommand, minted }`.\n\nActivation is two files in one folder on the host, plus two commands run from that folder:\n\n1. **`compose.yaml`**: `composeText`, saved under the name `composeFileName` gives.\n2. **`dtwo.env`**: the activation pair, exactly two lines.\n\n ```\n ACTIVATION_ID=<activationId>\n ACTIVATION_CODE=<activationCode>\n ```\n\n3. Then, from that folder, pull the image and start the stack:\n\n ```bash\n docker compose --env-file dtwo.env pull\n docker compose --env-file dtwo.env up -d\n ```\n\nBuild those commands yourself as written above rather than echoing the `activationCommand` field. That field still returns an older form that writes the pair into a `.env` file, which works but doesn't match the Dtwo Hub or its docs, and a leading-dot filename is easy to lose (browsers rename it on download, and `ls` hides it). The file name `dtwo.env` is what the Hub uses, and the `--env-file` flag is what makes a visible name work.\n\nThe credentials are **single-use and valid for 24 hours** from when they were minted. `activationExpiresAt` carries the exact expiry if the user asks.\n\n**The user decides who runs this, not your environment.** Where you can run shell commands (Claude Code with Bash), offer to do it and say what that involves: creating a folder with two files in it and starting a container. Ask before touching anything. Two ways it can go:\n\n- **They accept.** Ask which folder to use, write both files there, then run the two commands from that folder. No need to print the activation pair when you're the one writing the file. Stream the result back and confirm the container came up.\n- **They'd rather do it themselves**, or you have no shell (claude.ai, Claude Desktop without one). Hand over everything they need as copyable blocks with a line of explanation each: `composeText` (titled `composeFileName`), the two `dtwo.env` lines with the **real `activationId` and `activationCode` filled in**, and the two commands. Say that both files go in the same folder and the commands run from there. Then wait for them to confirm they've run it before continuing.\n\nPrint the real values in that second case. The pair is a credential, so don't scatter it around unasked, but a user who has said they'll run the commands themselves needs the actual id and code, and a placeholder or an offer to write the file for them instead is just an obstacle. Someone who came to a skill for guidance may well not want it creating files on their machine, and that's a reasonable thing to want.\n\n**Expired or missing credentials are handled for you.** The activation code is never stored, so `dtwo-create-gateway-activation` mints a fresh pair on every call and reports `minted: true`. There is nothing to do about expiry up front, and no reason to check it before starting.\n\nIf a first attempt needs another go, which tool to call depends on whether the host is up:\n\n- **The host has never come up** (the normal case here, including a first attempt whose code expired before the user ran it): call `dtwo-create-gateway-activation` again, then hand over or write the new pair the same way as the first attempt, and run the same two commands. The `pull` matters, since the image may still not be on the host.\n- **The host is already up** and reported an invalid or expired code at run time: call `dtwo-refresh-gateway-activation` `{ uid }`, hand over or write the new pair into `dtwo.env` as before, and re-register with one command instead:\n\n ```bash\n docker compose --env-file dtwo.env up -d --force-recreate\n ```\n\n `--force-recreate` is what makes Compose rebuild the container so it picks up the new pair, and leaving `pull` out keeps the host on the image it is already running.\n\n**Create the activation once per attempt.** Do not call `dtwo-create-gateway-activation` again after the container has started with the pair you were given: another call mints a new one and invalidates the one the host just used. Calling it again is only right when the attempt didn't finish, as in the first case above. Create once, activate, then move on to Phase 10.\n\n**Then wait for the gateway to check in.** Starting the container isn't the same as the platform knowing about it. Check `dtwo-get-gateway` `{ uid }`: while `status` is `provisioning` or `provisioned` the gateway hasn't checked in yet and has nothing for a deploy to land on. Once it reaches `registered` or `running`, Phase 10 can go ahead. If it sits in `provisioned` for more than a minute or two, the container is up but can't reach Dtwo, so check the container logs rather than deploying into it.\n\n### Phase 10 — Deploy\n\n**If authentication was parked in Phase 4, stop and ask before deploying.** Deploying now puts a gateway on the network with client authentication off: anyone who can reach its URL can call every MCP server behind it, and no policy you attached changes that. Say that in as many words, then offer the safer resting point: leave the config published and undeployed, finish authentication when the URL is ready, and deploy after that. Everything built so far is saved either way. If they'd still rather deploy now, say what they're deciding, deploy, and remember it: Phase 11 reports `authMode: none` and needs to repeat the warning, and this is the first thing to fix when they come back.\n\n**Check the gateway has checked in before deploying.** A deploy needs a gateway the platform can reach: while `dtwo-get-gateway` reports `status: provisioning` or `provisioned`, it hasn't checked in and the deploy has nowhere to land. Wait for `registered` or `running`: for hosted that's provisioning finishing, and for local and self-hosted it's the container coming up in Phase 9.\n\nConfirm with the user, then call `dtwo-deploy-gateway` `{ uid }`. Capture the returned task UID and poll `dtwo-get-deployment` until `status: \"completed\"` (or a failure).\n\n- Follow the polling and transient-error guidance in **dtwo-gateway-config** / **dtwo-gateway-policy** (a config deploy briefly restarts the gateway; a `502` during the restart window is expected and recovers, while `\"MCP server is not connected\"` means the user must reconnect).\n- **On failure**, surface the task error message plainly and offer concrete fixes (e.g. a config validation problem → back to Phase 5; provisioning not finished for hosted → wait and re-check `dtwo-get-gateway`; activation not completed for self-hosted → back to Phase 9; another deploy of the same gateway still running → wait for it and queue this one again).\n\n**Show progress — checkpoint 4 of 6, do this now.** Redraw the list with **Create your gateway**, **Configure auth**, **Add MCP servers**, and **Add policies** checked off. Still to come: Connect AI client (Phase 11), Test policies (Phase 12).\n\n### Phase 11 — Connect\n\nCall `dtwo-get-gateway-connection-info` `{ uid }` and render ready-to-paste connection instructions from the returned `mcpUrl`, `authMode`, `clientId`, and `callbackPort`. This works on every deployment type, self-hosted included: a `standard` gateway reports the same connection details as any other once it has a URL.\n\n**What comes back is your working material, not a report to read out.** Name a URL, client id, audience, or issuer only where the user has to put it somewhere themselves, and never to say that one isn't needed: \"no client id required\" only puzzles someone who never knew a client id existed. A user who asked you to connect the gateway for them wants to hear that it's connected.\n\nRead `authMode` before writing the instructions, because it decides what you can promise:\n\n- **`dtwo`**: the Dtwo-managed IdP. Sign-in needs nothing from the user beyond completing the browser flow. Use `clientId` where the client below asks for one.\n- **`custom`**: the user's own IdP. `mcpUrl`, `audience`, `issuer`, and `jwksUri` come back; `clientId` does not, and its absence is correct rather than a failure. Say that sign-in goes through their own IdP. If they're connecting the client themselves, name the returned issuer too, so they can see which one the gateway will accept, and where a client below wants a client id, tell them to use the one they registered with their IdP.\n- **`none`**: authentication is off, so `mcpUrl` is all there is. Say plainly that anyone who can reach the URL can use the gateway, in case that isn't what they intended, and offer to go back to Phase 4 and configure it, which on a `standard` gateway means setting the URL first. It's a live gateway at this point, so treat this as the thing to fix rather than a footnote on the connection instructions.\n- **`unknown`**: the saved config couldn't be read, usually a YAML problem. Don't guess at connection instructions. Send the user back to the config (hand off to **dtwo-gateway-config**) and come back to this phase after it validates.\n\nUse a kebab-case token for `<name>` (derive it from the gateway name; the Dtwo Hub falls back to `dtwo-gateway` when a gateway has no usable name). Pass `<clientId>` wherever a client below takes one and the tool returned it: clients that carry a Client ID Metadata Document (Claude's own surfaces, Claude Code, and Codex) identify themselves and connect from `mcpUrl` alone, while other clients such as Cursor need it spelled out. Never pass the returned `clientId` to a CIMD client: Codex's `--oauth-client-id` is only for a `custom` gateway, with the client id the user registered with their own IdP. `callbackPort` comes back only for a `custom` gateway: it is the loopback port to register as a redirect URI with their IdP, for a client that signs in with that IdP's client id and lets you choose its callback port. It must not override Cursor desktop’s fixed `http://localhost:8787/callback` redirect.\n\nChoose instructions for the current AI client, then use its available shell or file-editing tools:\n\n**Running in Claude Code with shell access.** Offer to register the gateway as an MCP server directly by running `claude mcp add` for the user. Confirm first, and confirm the server `<name>` (the kebab-case token described above). If they'd rather run it themselves, hand them the command filled in and let them, the same as in Phase 9: this one edits their client config, so it's theirs to run if they want it that way. Either way the command is:\n\n```bash\nclaude mcp add --transport http \\\n <name> <mcpUrl>\n```\n\nAfter it succeeds, tell the user the server is registered, that the OAuth flow completes in the browser on first use, and that they may need a new or reloaded session before the server shows up. Name the server, and leave the connection parameters out: the command already carried the URL, no client id was needed, and listing either turns a finished job back into homework. Mention that other client options (the `.mcp.json` form, or Cursor) are available if they want to connect a different client, and show those only if they ask.\n\n**Running in Codex with shell access.** The same, with `codex mcp add`. Confirm first, and confirm the server `<name>`:\n\n```bash\ncodex mcp add <name> --url <mcpUrl>\n```\n\nFor a `custom` gateway, append `--oauth-client-id '<client id from their IdP>'`. Sign-in starts in the browser; if it doesn't, run `codex mcp login <name>`. Then tell the user the server is registered and name it, leaving the connection parameters out.\n\n**Other hosts (including Cursor), or no shell access.** Use the current host’s connection option below. If you can edit its configuration, offer to merge the entry after confirmation; otherwise present its copyable instructions. Show other client options only on request.\n\nClaude Desktop (Cowork), through the connector settings UI — walk them through the click path since there's no config file to hand them. **Skip this option for a `localHttp` gateway:** the connector is added through Anthropic's own UI, which takes an HTTPS URL it can route to, and a local gateway serves plain HTTP on the user's own machine. Offer Claude Code or Cursor there instead.\n\n1. In Claude Desktop, open **Settings** and go to **Connectors**. Select **Add custom connector** (the exact wording varies slightly by version, so look for \"Add connector\" or similar under Connectors settings if that path doesn't match).\n2. Name the connector `<name>` (the kebab-case token described above).\n3. Set the server URL to `<mcpUrl>`.\n4. Select **Connect**, and complete the OAuth sign-in in the browser when prompted.\n5. Start a new chat and switch `<name>` on in the connectors menu. Don't leave this step out: a connector that's added but left off is never called, and it's the step people miss most often.\n6. Ask Claude what tools it has. The gateway's tools should be in the list.\n\nClaude Code, a CLI add plus an `.mcp.json` snippet (for a `custom` gateway, append `--client-id '<client id from their IdP>' --callback-port <callbackPort>` to the command):\n\n```bash\nclaude mcp add --transport http \\\n <name> <mcpUrl>\n```\n\n```json\n{\n \"mcpServers\": {\n \"<name>\": {\n \"type\": \"http\",\n \"url\": \"<mcpUrl>\"\n }\n }\n}\n```\n\nCodex, a CLI add (append `--oauth-client-id '<client id from their IdP>'` only for a `custom` gateway), then `codex mcp login <name>` if sign-in doesn't start:\n\n```bash\ncodex mcp add <name> --url <mcpUrl>\n```\n\nCursor, an HTTP MCP server entry in `~/.cursor/mcp.json` (or a project-local `.cursor/mcp.json`) that carries the static client id under `auth.CLIENT_ID`:\n\n```json\n{\n \"mcpServers\": {\n \"<name>\": {\n \"url\": \"<mcpUrl>\",\n \"auth\": {\n \"CLIENT_ID\": \"<clientId>\"\n }\n }\n }\n}\n```\n\n**If `authMode` is `none`, omit Cursor's `auth` object entirely.** If authentication is enabled but `clientId` is absent, a CIMD connection (Claude, Claude Code, Codex) can still proceed. Cursor needs a registered public client ID: for Dtwo-managed authentication, ask the Dtwo administrator to configure the tenant's gateway client application; for a custom IdP, ask for its registered client ID. Stop Cursor's connection step until it is available. Never substitute the management plugin's client ID or attempt DCR.\n\n**If the call errors because the gateway has no URL**, don't present partial instructions. Two causes, with different fixes:\n\n- **A `standard` gateway with no URL yet.** Ask whether they have the address now. If they do, set it with `dtwo-update-gateway` `{ uid, url }`, configure authentication (Phase 4), and come back here. If they don't, say what's left to do and leave the connection step for a later session — nothing changes here on its own.\n- **A `hostedAws` gateway still provisioning.** Dtwo assigns the URL when provisioning finishes, so this one is a genuine wait. Check `dtwo-get-gateway`, and re-run `dtwo-get-gateway-connection-info` once it completes.\n\nWait for the user to actually confirm the connection is registered before doing the following — don't assume it's done just because you presented the instructions, especially on the Claude Desktop / manual-config paths where you have no way to verify it yourself:\n\n**Record the step.** Once they've confirmed, call `dtwo-record-setup-progress` `{ steps: [\"connectClient\"] }`. Nothing on the platform can see a client being registered, so the Dtwo Hub would otherwise still ask them to confirm it by hand. Don't mention the call; if it fails, carry on with setup and don't raise it (see **Graceful degradation**).\n\n**Show progress — checkpoint 5 of 6, do this now.** Redraw the list with every step checked off except **Test policies**. One checkpoint left, at Phase 12.\n\nThen move on to Phase 12 — setup isn't finished until the user has authenticated to the gateway and seen a policy do its job.\n\n### Phase 12 — Authenticate and test the policies\n\n**Authenticate to the gateway MCP.** In Claude Code, offer both routes:\n\n- The direct route: just ask the agent to use the new server (e.g. \"authenticate to `<name>`\" or \"list the tools on `<name>`\") — the first call triggers the OAuth flow in the browser.\n- The manual route: run `/mcp`, select the newly added gateway server in the list, and choose **Authenticate**. If the server doesn't show up in the list, run `/reload-plugins` and check `/mcp` again.\n\nIn Cursor, enable the gateway server in Customize and complete its browser sign-in; verify a tool call before continuing. In other clients without those commands (e.g. Claude Desktop), the first use of the connector triggers the auth flow in the browser instead.\n\n**If that first sign-in fails, clear the server's authentication and try once more.** In Claude Code that's `/mcp`, select the server, and choose **Clear authentication** (wording varies a little by version); other clients have an equivalent under the connector's own settings, sometimes as disconnecting and reconnecting it. Then authenticate again.\n\nTry this before digging into the config, because it's quick and it's a common cause: clients cache OAuth state per server, including what they discovered from the gateway URL, and a stale entry can outlive the gateway it came from. It matters most for a user who has used Dtwo before and is setting up again, where the cached state can belong to an older gateway at a different URL. It's worth one attempt even on a first-ever setup, since a server added, removed, and re-added under the same name can leave the same residue.\n\nIf a clear-and-retry doesn't fix it, stop guessing and check the two things that actually decide sign-in: that `dtwo-get-gateway-connection-info` reports the `authMode` you expect and an `mcpUrl` matching what the client is pointed at, and that the gateway's latest deploy carried the authentication config (an auth change saved but never deployed is the other common cause). On a custom IdP, add the callback-registration check from Phase 4.\n\n**Test the attached policies.** Pick one of the policies attached in Phase 7 and trigger the behavior it governs *through* the gateway, using one of the MCP servers added in Phase 5. Show the user the gateway's actual response verbatim — not just your summary of it — so they see the enforcement with their own eyes, then add your own one-line confirmation on top:\n\n- For a **redaction/transform policy**, make a call whose result would contain the redacted data. Quote the relevant part of the response back exactly as the gateway returned it (including markers like `[REDACTED]`), then confirm in your own words that the sensitive data came back transformed. Example: with an email-redaction policy attached, use one of the added MCP servers in a way that would return email addresses (say, searching a docs or repository server for maintainer contact info), show the returned text with the redaction marker in place, and confirm the addresses were removed.\n- For a **blocking/deny policy**, attempt the call the policy blocks and show the gateway's deny message verbatim, then confirm that's the policy doing its job.\n\nDon't paraphrase or describe the redaction/deny output in place of showing it — the point of this phase is for the user to see the gateway actually intercept the call, not just take your word for it.\n\nIf the user skipped policies in Phase 6, skip the test, and remind them the gateway is currently a pass-through — nothing is enforced until a policy is attached. Don't stop there without a closing moment — still finish with a short setup-complete close, just without a policy test to point to.\n\n**Record the closing steps.** Call `dtwo-record-setup-progress` once with every step that actually happened, so the Dtwo Hub reflects the setup you just ran instead of asking the user to confirm it again:\n\n- `testPolicies`, only if the policy test above ran and the gateway's own response showed the policy firing. Leave it out if policies were skipped in Phase 6 or the test didn't happen; a skipped test is a genuinely unfinished step, and the Hub should keep offering it.\n- `plugin`, only if you're running as the installed Dtwo plugin (including Claude Code and Cursor). Leave it out if you got here another way, such as the Dtwo MCP server connected on its own in a chat surface.\n\nSo a full run through the installed plugin sends `{ steps: [\"testPolicies\", \"plugin\"] }`. Same as Phase 11: don't narrate the call, and if it fails, finish setup normally without raising it.\n\n**Show progress — checkpoint 6 of 6, final one.** If the policy test ran, redraw the list with all six steps checked off. If the test was skipped, redraw it with **Test policies** left unchecked (or marked \"skipped\") and the other five checked. Either way, say something short marking setup as complete rather than describing what's next — a skipped test doesn't mean setup isn't done.\n\nClose by telling them how to manage config and policies going forward with the companion skills (`dtwo-gateway-config`, `dtwo-gateway-policy`, `dtwo-policy-rego`).\n\n---\n\n## Resuming a partial setup\n\nSetup can be interrupted. Before starting from scratch, infer what's already done and continue from the first incomplete phase:\n\n1. `dtwo-list-gateways` / `dtwo-get-gateway` — does the gateway exist? What's its `deploymentType` and provisioning/heartbeat state? (Exists → Phases 1–3 done.)\n2. For a `standard` gateway, does it have a `url`? A self-hosted gateway with no URL is a normal resting state, since everything but authentication and the connection step can be done without it, so it's often exactly why the user came back. Ask whether they have the address now: if so, pick up at Phase 3's URL step, and otherwise carry on from whatever else is unfinished.\n3. `dtwo-get-gateway-config` — is `gateway.authentication` set (Phase 4)? Are there `mcp_servers` entries (Phase 5)? A missing `authentication` block on an already-deployed gateway means it is running with client authentication off: say so, and offer that as the first thing to pick up.\n4. `dtwo-get-gateway-pipelines` — are policies attached (Phases 6–7)?\n5. Published version present and a completed deployment (`dtwo-get-gateway-deployments`)? → Phases 8–10 done; likely just needs **Connect** (Phase 11) and **Authenticate and test** (Phase 12).\n6. `dtwo-get-setup-progress`: which closing steps did an earlier run already record (Phases 11 and 12)? Treat these as a hint rather than proof: they say a previous run got that far, not that the client still works. Confirm with the user before skipping one. Re-recording is harmless in any case, since the tool merges.\n\nTell the user what you found (\"Looks like your gateway exists with two MCP servers but no policies attached yet — want to pick up at the policies step?\") and continue from there rather than redoing completed work.\n\n## Graceful degradation\n\nThe progress-recording tools (`dtwo-record-setup-progress`, `dtwo-get-setup-progress`) are the one exception to everything below: they only keep the Dtwo Hub's view of setup in step with what you did, so if either is missing or a call fails, carry on and finish setup as normal. Don't retry, don't mention it, and don't let it become the last thing the user hears. The only cost is that the Hub still lists the closing steps as unconfirmed, and the user can tick them off there.\n\nIf any other setup-specific tool this skill relies on (`dtwo-create-gateway`, `dtwo-update-gateway`, `dtwo-set-gateway-auth`, `dtwo-get-gateway-connection-info`, `dtwo-create-gateway-activation`, `dtwo-refresh-gateway-activation`) is **not present** in your available tool list, the connected Dtwo environment doesn't support plugin-driven setup yet. Don't try to reconstruct these steps by hand. Instead, tell the user plainly and point them to the Hub's own guided setup, which walks through the same journey in the web app: open the account menu at the bottom of the left sidebar and choose **Setup guide**. The other companion skills still work for managing a gateway once it exists.\n\n## Limitations\n\n- This skill orchestrates setup but does not itself own the config schema, policy lifecycle, or Rego — it hands those to the three companion skills.\n- It cannot delete a gateway (do that in the Hub, from the **⋯** menu at the top right of the gateway's page) or complete IdP-side setup for a custom identity provider (the user configures their IdP; the skill only records the JWKS parameters).\n- Hosted provisioning and self-hosted activation happen partly outside the MCP surface (AWS provisioning, the user's Docker host) — the skill checks status and guides, but can't force those external steps to finish.\n"
}SHA-256 of public snapshot: 196fa4f94d3f539d2400a6d8e69119bd908b0cd209a4ad092430dae4f6613920