# Trigger the next step.

Exact commands for displaying a guide, registering a request and checking status, with their availability made explicit.

> **Request interface: implemented preview.** The request link, inbox and status MCP described here belong to Keyhole's preview branch, checked at `50d6803`. They are not included in the released 0.1.0, which provides `Keyhole: Set a Secret in .env…`. Porthole's local-file opening interface is released in 0.4.1.

 

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](https://jlumbroso.github.io/keyhole-docs/render-mcp.html) or [Neon](https://jlumbroso.github.io/keyhole-docs/neon-mcp.html) 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](https://jlumbroso.github.io/keyhole-docs/assistant-settings.html) 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](https://jlumbroso.github.io/porthole-docs/terminal-and-agents.html).

 

## 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](https://jlumbroso.github.io/keyhole-docs/first-secret.html).

 

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](https://jlumbroso.github.io/keyhole-docs/keeping-secrets-out-of-the-conversation.html).

 

## Reference status

 

Checked against [Keyhole preview source at 50d6803](https://github.com/jlumbroso/keyhole/tree/50d68037f398797643a4da39f59da4eb545c98e5/src) and [Porthole 0.4.1](https://github.com/jlumbroso/porthole/releases/tag/v0.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.

## Chapter notes

**Preview contract**

Keyhole requests and secret_status are implemented on an unreleased branch. Version 0.1.0 supports manual entry only.

**Names cross**

Requests carry names and instructions. The person supplies the value in VS Code.

Keyhole 0.1.0 · previews labeled separately. Updated 24 October 2026. [Online chapter](https://jlumbroso.github.io/keyhole-docs/for-assistants.html). [Source reference](https://github.com/jlumbroso/keyhole/blob/main/docs/manual/content/for-assistants.html).

Source access currently requires a repository invitation.