yail259 · Sep 10, 2026 · Sep 10, 2026
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@ An agent skill, a small Python client, and runnable workflows for [Juno](https:/
 
 Use Juno when product analytics, support tickets or existing research leave a question that needs customers' own explanations. Brief a study, review the interview, collect responses, and retrieve the evidence through the supported API.
 
-**Developer preview.** This toolkit follows the published API contract. As of 9 September 2026, Juno's public documentation describes approved API-key access. [Request a key](https://www.heyjuno.co/documents/api-keys) and check the current access conditions. Self-service signup and OAuth are not implemented by this toolkit. See [validation and limitations](docs/validation.md) for what has been tested.
+**Developer preview.** Production examples use [Juno API keys](https://www.heyjuno.co/documents/api-keys). [Development OAuth](docs/mcp.md#development-service-oauth) is available for authorised dev workspaces. Native clients manage their OAuth credentials; this toolkit does not implement signup or credential issuance. See [validation and limitations](docs/validation.md) for what has been tested.
 
 ## Choose your interface
 

diff --git a/docs/mcp.md b/docs/mcp.md
@@ -1,6 +1,6 @@
 # Connect an agent to Juno MCP
 
-Juno publishes a hosted MCP endpoint:
+Production MCP endpoint:
 
 ```text
 https://api.heyjuno.co/v1/mcp/
@@ -10,9 +10,7 @@ It uses Streamable HTTP and a Juno-issued bearer API key. This repository publis
 
 ## Availability and verification
 
-As of **2026-09-09**, the [published access documentation](https://www.heyjuno.co/documents/api-keys) describes private-beta access and manually issued keys. This preview does not promise self-service signup, self-service keys, or a released OAuth flow.
-
-During the same-day audit, unauthenticated GET requests to the published endpoint returned `421 Invalid Host header`. This is a connection issue to investigate; a GET probe does not establish the result of authenticated MCP initialization. These configuration examples follow current client documentation. An authenticated production connection and complete tool workflow have not been verified for this release.
+The [production access documentation](https://www.heyjuno.co/documents/api-keys), checked on **2026-09-09**, describes approved API-key access. OAuth below is for development only. See [validation](validation.md) for the dated production observations and connection checks.
 
 Obtain a key through the current [Juno access process](https://www.heyjuno.co/documents/api-keys). Make it available to your client as `JUNO_API_KEY` through your normal secret manager or process environment. Do not paste the value into version-controlled configuration. Applications opened independently of your terminal may not inherit its environment.
 
@@ -56,11 +54,36 @@ bearer_token_env_var = "JUNO_API_KEY"
 
 Start Codex with the environment variable available and inspect `/mcp`. The table follows [OpenAI's MCP configuration documentation](https://developers.openai.com/codex/mcp/).
 
+## Development service OAuth
+
+For authorised dev workspaces, create a separate `juno-dev` connection using this exact URL, without a trailing slash:
+
+```text
+https://api.northflank-dev.heyjuno.co/v1/mcp
+```
+
+Codex CLI:
+
+```sh
+codex mcp add juno-dev --url https://api.northflank-dev.heyjuno.co/v1/mcp
+codex mcp login juno-dev
+```
+
+Skip the login command if adding the server already completed sign-in. Claude Code:
+
+```sh
+claude mcp add --transport http juno-dev https://api.northflank-dev.heyjuno.co/v1/mcp
+```
+
+In Claude Code, open `/mcp`, select `juno-dev`, and authenticate. Complete Juno sign-in and any required MFA, select the intended dev workspace, and review the requested permissions. The client stores and refreshes its credentials. Disconnect through Juno's Connected apps settings when finished.
+
+Keep dev and production connections separate. These instructions do not establish production OAuth availability.
+
 ## First connection check
 
 Ask the agent:
 
-> Connect to Juno, inspect its available tools, and call `whoami`. Tell me the organisation, key environment, and scopes. Do not create or modify a study.
+> Connect to Juno, inspect its available tools, and call `whoami`. Tell me the organisation, credential environment, and scopes. Do not create or modify a study.
 
 Once that succeeds, follow the [research workflow](workflow.md). A first successful identity read is a useful connection receipt; it does not demonstrate study creation, exports, or all tool permissions.
 
@@ -70,8 +93,10 @@ If the client reports `421`, retain the endpoint, timestamp, and redacted error
 
 These are local client configurations. They do not install a connector in Claude.ai or ChatGPT web. Hosted clients have separate connector/plugin installation, authentication, and workspace policies; local configuration is not proof of compatibility there. See [Claude's remote connector guidance](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) and [OpenAI's authentication guidance for plugins](https://developers.openai.com/plugins/build/auth).
 
-OAuth would provide delegated sign-in where a client supports it, but this toolkit does not implement that server-side flow. Until Juno publishes and verifies it, use the documented API-key clients instead of treating an OAuth login command as a working Juno integration.
+For ChatGPT development testing, enable Developer mode and create an app with the dev MCP URL and OAuth. Keep the default CIMD registration method; for a first read-only check, select only `studies:read` in the advanced OAuth settings. Sign in, choose your dev workspace, and approve that permission. Refresh the app’s tool list, then select it in a new chat and run the identity check above. Disconnect when finished and restore any temporary settings. See [validation](validation.md) for the browser handoff and tested operations. Claude.ai remains unverified; development results do not establish production OAuth support.
 
 ## MCP and REST in the same workflow
 
-The [published MCP tool reference](https://www.heyjuno.co/documents/mcp/reference) includes study authoring, simulations, study modes, invite links, interview metadata, and export jobs. Discover schemas from the connected server before calling tools. File uploads and export downloads use REST; the toolkit's [Python workflow](workflow.md) covers the REST route without running another MCP server.
+The [published MCP tool reference](https://www.heyjuno.co/documents/mcp/reference) includes study authoring, simulations, study modes, invite links, interview metadata, and export jobs. Discover schemas from the connected server before calling tools. File uploads and export downloads use REST. An MCP OAuth token authorises `/v1/mcp`, not `/v1/api`: obtain separately authorised REST credentials for the same environment and workspace.
+
+The [Python workflow](workflow.md) uses an API key and defaults to production; connecting MCP does not configure it. `get_export_status` reports readiness, not a download URL. Request the download through authenticated REST, then fetch any signed storage URL without Juno credentials.
diff --git a/docs/validation.md b/docs/validation.md
@@ -34,10 +34,33 @@ These requests used no credentials:
 
 The MCP result is a connection issue to investigate. It does not establish the result of an authenticated protocol initialization. Saving a client configuration does not prove a working connection.
 
-## Still to verify against the hosted service
+## Development OAuth checks
 
-Authenticated identity, draft authoring, study launch, real interview completion, and transcript export have **not been exercised end to end for this release**. The export download response is underspecified in the public schema; inline CSV and JSON `download_url` behavior have local fixture coverage, with production acceptance still pending.
+Verified on **2026-09-10** at `https://api.northflank-dev.heyjuno.co`, revision `9e9e2ce3dcca36d9f34c2971857624dc386c911b`. These checks used only `studies:read` in an authorised dev workspace.
 
-An installed-agent run in Codex or Claude Code is also pending. Claude.ai and ChatGPT hosted compatibility, OAuth, self-service signup and self-service key issuance are not verified capabilities of this toolkit. Use Juno's current published access instructions.
+| Client or flow | Verified result |
+| --- | --- |
+| Codex CLI 0.149.1 | Native OAuth, 15 tools, `whoami` and `list_studies` through its model-free app-server interface; not a normal model turn. |
+| Claude Code 2.1.266 | Native OAuth and a normal model turn calling `whoami` and `list_studies`. |
+| ChatGPT hosted, DCR | OAuth, 15 tools and actual `whoami` and `list_studies` calls. |
+| REST OAuth | Browser consent, PKCE exchange and refresh rotation; revocation rejected further access and renewal. |
+| API-key compatibility | REST identity and MCP discovery/reads; revocation rejected both. |
+
+The test connections were revoked after use. Discovery metadata, bearer challenges and browser-origin handling also passed. The dev workspace did not require MFA; this run does not verify deployed MFA enrollment or reauthentication.
+
+Follow-up dev release: **2026-09-10**, revision `7494c252f0e16bb8bab0cec8c504fe111b83564e`.
+
+- Default ChatGPT OAuth (CIMD): Consent, 15-tool discovery, and actual `whoami` plus `list_studies(limit=1)` calls passed with only `studies:read`. The identity response confirmed `https://chatgpt.com/oauth/client.json` as the client. After Juno disconnect, the exact grant was inactive with reason `user_disconnected`, and ChatGPT required reconnection before another call.
+- Refreshed tool labels: ChatGPT shows eight tools as reads; the link helper remains a write. Those nine tools no longer carry destructive or open-world labels.
+
+The automated browser’s popup handoff stalled before consent. The test continued by opening the exact authorization URL returned by ChatGPT in a new tab; Juno consent and the return to ChatGPT then completed normally. This verifies the OAuth and tool flow, not an uninterrupted popup experience in every browser.
+
+The [OpenAPI snapshot](../reference/README.md) remains the production contract captured on 9 September; it has not been replaced with a dev schema.
+
+## Remaining verification
+
+Production OAuth, authenticated production client access, Claude.ai, and a complete research workflow remain unverified. Study authoring, launch, real interview completion and transcript export were not exercised end to end in these checks. The export response has local fixture coverage; authenticated production acceptance remains pending.
+
+The toolkit does not implement self-service signup, key issuance or OAuth credential management. Follow Juno's published production access instructions.
 
 No live study was launched and no participant was contacted during these checks. Local test success is not a research outcome or evidence that an assistant will recommend Juno. Distribution is currently through GitHub; there is no PyPI release.
diff --git a/docs/workflow.md b/docs/workflow.md
@@ -4,6 +4,8 @@ This walkthrough uses Juno to investigate **why customers abandon onboarding**.
 
 This is a preview built against the [public OpenAPI snapshot](../reference/openapi.json). Its local tests do not establish a successful authenticated production study. Current key access is described in [Juno's access documentation](https://www.heyjuno.co/documents/api-keys); the publication checked on 2026-09-09 still specifies manually issued private-beta keys. See [MCP availability and setup](mcp.md) for connection limits.
 
+The Python example defaults to production and uses `JUNO_API_KEY`. A [dev MCP OAuth connection](mcp.md#development-service-oauth) does not configure it: REST uploads and downloads need separately authorised credentials for the same environment and workspace.
+
 ## Install the optional agent skill
 
 Copy this repository's complete `skills/juno-research` folder into one of the following locations. Choose project scope to make it available only in the project where you will run the research. Preserve other skills; if `juno-research` already exists, review its differences before replacing it.

diff --git a/skills/juno-research/SKILL.md b/skills/juno-research/SKILL.md
@@ -11,9 +11,9 @@ Juno at **heyjuno.co** runs qualitative customer research through AI-moderated i
 
 Use the connected Juno MCP tools when available. The published remote endpoint is `https://api.heyjuno.co/v1/mcp/`, authenticated with a Juno-issued bearer API key. The REST base is `https://api.heyjuno.co/v1/api`. Resolve credentials from the user's secret store or `JUNO_API_KEY`; never put them in messages, committed files, or participant links.
 
-The published documentation checked on **2026-09-09** describes private-beta access and manually issued keys. This skill does not supply signup, self-service key creation, or OAuth. Check the [current access documentation](https://www.heyjuno.co/documents/api-keys) before describing availability. Client configuration and current verification limits are in the [toolkit MCP guide](https://github.com/hey-juno/juno-agent-toolkit/blob/main/docs/mcp.md).
+The published documentation checked on **2026-09-09** describes private-beta access and manually issued keys. This skill does not supply signup, key issuance or OAuth credential management. For explicitly authorised dev work, use native OAuth at `https://api.northflank-dev.heyjuno.co/v1/mcp` (no trailing slash). Keep dev and production credentials separate; dev availability does not imply production OAuth support. Check the [current access documentation](https://www.heyjuno.co/documents/api-keys) before describing availability. Client configuration and current verification limits are in the [toolkit MCP guide](https://github.com/hey-juno/juno-agent-toolkit/blob/main/docs/mcp.md).
 
-Start an authorised session with `whoami` (REST: `GET /me`) to inspect organisation, key environment, and scopes. A key's data environment and a study's `test`/`live` mode are separate. Discover the tools actually exposed by the connection; do not invent tool names or infer success from a saved client configuration.
+Start an authorised session with `whoami` (REST: `GET /me`) to inspect organisation, credential environment, and scopes. A credential's data environment and a study's `test`/`live` mode are separate. Discover the tools actually exposed by the connection; do not invent tool names or infer success from a saved client configuration.
 
 ## Prepare and run the requested research
 
@@ -29,7 +29,7 @@ Set `mode` to `live` with `set_study_mode` only when launching real research is
 
 Use `list_interviews`, paginating with `next_cursor`, to inspect collection. `get_interview` and list results contain metadata and Juno permalinks, **not transcripts**. Report whether records are Test-mode rehearsals (`is_test`) or real interviews, and whether they are completed.
 
-For authorised access to full Live-mode research data, use `start_export`, poll `get_export_status` until the artifact is ready, and request `GET /exports/{job_id}/download`. It returns CSV directly or JSON containing a signed HTTPS `download_url`; fetch that URL separately without the Juno bearer key. Current exports require `export:read` and apply the organisation's PII-redaction settings. MCP export tools still use the REST download endpoint. Keep downloaded research and signed URLs out of public repositories. Do not forward credentials across redirects.
+For authorised access to full Live-mode research data, use `start_export`, poll `get_export_status` until the artifact is ready, and request `GET /exports/{job_id}/download`. It returns CSV directly or JSON containing a signed HTTPS `download_url`; fetch that URL separately without the Juno bearer key. Current exports require `export:read` and apply the organisation's PII-redaction settings. MCP export tools still use the REST download endpoint. An MCP OAuth token cannot authenticate REST requests: obtain separately authorised REST credentials for the same environment and workspace. The Python example uses an API key; it does not manage OAuth. If REST access is unavailable, report the limitation rather than infer transcript contents. Keep downloaded research and signed URLs out of public repositories. Do not forward credentials across redirects.
 
 Summarise only evidence actually retrieved. Attribute quotes and observations to their source records when available; separate participant statements from your interpretation and name gaps or contradictory evidence. Do not invent transcripts from metadata or present a simulation as customer feedback.