Trigger the next step.

Initiate the step that needs the person. Prepare the instructions, display them through Porthole, and submit a Keyhole request containing the setting's name and purpose. The person obtains the credential and supplies its value in Keyhole. Continue from the recorded status without asking for the value in chat.

Choose the handoff before requesting a token

1. Identify the service, task and credential type. For MCP access, start with the Render or Neon guide. If browser authorization is sufficient, use that route instead of requesting an API key.
2. Identify the receiving process and destination. A project's .env is not automatically available to every MCP server. Check assistant settings before promising a complete setup.
3. Explain what access the credential grants. Ask only for the names the chosen setup needs; never request a value through a tool argument, URL or conversation.
4. Confirm the person has a build with the interface below. If not, display the guide and explain the current Command Palette entry flow.

1. Display a local guide with Porthole

Porthole opens an existing local Markdown or HTML file. It does not open the manual's remote URL directly. Run the download from the selected workspace folder's root, so the shell and Porthole resolve the same relative path:

mkdir -p docs/keyhole && curl --fail --location 'https://jlumbroso.github.io/keyhole-docs/render-mcp.md' --output docs/keyhole/render-mcp.md

After the download succeeds, read the local guide before presenting it. Then, on macOS, open it with this credential-free command. Replace my-project with the receiving VS Code workspace folder's display name:

open 'vscode://jlumbroso.porthole/v1/open?file=docs/keyhole/render-mcp.md&repo=my-project&width=480&height=720'

For Neon, use neon-mcp.md in both the download and local path. Keep credentials out of the file. The OS sends the link to the last-used VS Code window; repo disambiguates a folder in that window, not a different window.

Executing open is a GUI action subject to your harness permissions. Printing a command or link is not executing it. Porthole gives no completion receipt to the caller, and opening a guide does not establish that the person has read it. See Porthole's terminal and agents reference.

2. Register a request by opening its URI

With the Keyhole preview installed, this harmless practice request records the name and announces it in VS Code:

open 'vscode://jlumbroso.keyhole/v1/request?name=KEYHOLE_PRACTICE&why=Try%20the%20request%20flow&repo=my-project'

The person chooses Keyhole: Show Inbox and selects the request when ready. The link does not immediately open a value box. With 0.1.0, the person instead runs Keyhole: Set a Secret in .env…, enters the agreed name, and follows the practice walkthrough.

Preview URI: vscode://jlumbroso.keyhole/v1/request

Parameter	Meaning
name	Required variable name. Repeat for multiple names, in the order requested. A request accepts 1–10 distinct names.
why	Optional short explanation of the task that needs the credential.
where	Optional description of where the person obtains it. This is not the output file or a configurable destination.
repo	Optional exact display name of an open local workspace folder. Without it, exactly one local folder must be open.

Encode query values. Names must match [A-Z][A-Z0-9_]*; names that alter command execution or sensitive runtime behavior are refused. Keep why and where to 500 characters each, without line breaks or control characters. Do not repeat these fields or repo. Avoid text containing an ampersand followed by a parameter-like name and equals sign; VS Code's pre-decoding makes that ambiguous in this preview.

There is no value, token or target parameter. Unknown fields are rejected. Allowed prose is not a secret detector: never hide a value inside why or where. The destination remains the chosen folder's .env.

Alternative: write the request record

An assistant that can edit project files can add the same request to .keyhole/inbox.json. Preserve existing rows. Use the current UTC time for asked; the date below is illustrative.

{
  "format": 1,
  "requests": [
    {
      "kind": "request",
      "names": ["KEYHOLE_PRACTICE"],
      "why": "Try the request flow",
      "asked": "2026-10-24T23:00:00Z"
    }
  ]
}

The file belongs to that project, so it has no repo field. Each row permits only kind, names, why, where and asked. The active extension watches the file. Requests already present at startup are not announced or initially refreshed; the URI is preferable for an active handoff. The record contains names and instructions, never values; it is intended to be shareable with the project.

The URI route and file route reach the same request checks. A repeated URI with the same ordered names does not add another row or update its description. Neither route returns a request ID or proves that the person submitted a value.

3. Connect the status MCP

In the preview, run Keyhole: Connect an Assistant…. It copies the registration command for the chosen harness, with the installed server's actual stable path. The person runs that command once. These are the source-derived command shapes; <server-path> is a placeholder, not a file to create:

claude mcp add --scope user --transport stdio keyhole -- node "<server-path>"
codex mcp add keyhole -- node "<server-path>"
gemini mcp add -s user keyhole node "<server-path>"
grok mcp add keyhole -- node "<server-path>"

These commands require node on the harness's PATH. VS Code's own chat is offered a Keyhole MCP provider separately. Connecting the server exposes a status tool; it does not create requests or display guides.

4. Call secret_status

The preview MCP has one tool, secret_status. Pass a required name and, preferably, the project's absolute path. Here are its arguments:

{
  "name": "KEYHOLE_PRACTICE",
  "project": "/absolute/path/my-project"
}

For an MCP client implementing the protocol directly, the corresponding tool-call message is:

{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"secret_status","arguments":{"name":"KEYHOLE_PRACTICE","project":"/absolute/path/my-project"}}}

Only name and project are accepted. If project is omitted, the server uses CLAUDE_PROJECT_DIR, then its working directory. Unlike the URI's repo, this is a filesystem path; it is not limited to currently open workspace folders.

Interpreting the structured result

Result	What it establishes
known: false	No readable cached entry. This is not proof that the variable is absent.
known: true, set: false	The cache records no matching assignment at checked. A missing or unreadable .env can also produce this result.
known: true, set: true	The extension found an assignment at checked, which may be empty. The result includes its length and keyprint; it does not establish a usable credential.

The MCP process reads .keyhole/status.local.json, not .env. The extension maintains that cache. Check the timestamp; do not turn a cached observation into a claim about a fresh write, a particular request, or service authentication. A keyprint can include a recognized public prefix and the last four characters of a long value.

Continue without the value

Distinguish these outcomes in your reply: guide displayed, request registered, setting observed, process configured, and service accepted a permitted operation. Resume only the work supported by the observed step. Do not print environment variables, read a secret-bearing file, or ask the person to paste it to diagnose a failure. Use the service guide's verification step and file protections.

Reference status

Checked against Keyhole preview source at 50d6803 and Porthole 0.4.1 on 24 October 2026. The Keyhole source link currently requires repository access. These examples are documentation/source checked, not a fresh end-to-end test in a running assistant or a provider account.