docs(readme): mention callOnce disableOAuth for headless callers

[feniix]

Summary

README follow-up requested in #201: the callOnce section (the README's recommended entry point for "agent tool hook" / headless use) still implied interactive OAuth was unavoidable. #198 shipped the disableOAuth option on callOnce and updated docs/mcp.md / docs/cli-reference.md, but not the README.

• Documents disableOAuth: true on the callOnce README section and cross-references the CLI's --no-oauth flag, matching the phrasing in docs/mcp.md.

Proof

Rendered README section after the change (GitHub-rendered on the PR branch):
https://github.com/feniix/mcporter/blob/docs/readme-callonce-disable-oauth/README.md#one-shot-calls-from-code

Copied rendered output of the updated paragraph:

callOnce automatically discovers the selected server (including Cursor/Claude/Codex/Windsurf/OpenCode/VS Code imports), handles OAuth prompts, and closes transports when it finishes. It is ideal for manual runs or wiring MCPorter directly into an agent tool hook. In headless contexts, pass disableOAuth: true to suppress interactive OAuth and rely on cached tokens only — the library equivalent of the CLI's --no-oauth flag.

Test plan

• Docs-only change; rendered Markdown reviewed (see Proof above).

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 10, 2026, 12:27 AM ET / 04:27 UTC.

Summary
The PR updates one README paragraph to document disableOAuth: true for callOnce in headless contexts and relate it to the CLI --no-oauth flag.

Reproducibility: not applicable. as a docs-only PR; source inspection shows current main’s README still omits the disableOAuth guidance while runtime support and related docs already exist.

Review metrics: none identified.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Next step before merge

• No automated repair is needed; the PR is narrow, proof-positive, and ready for normal maintainer review.

Security
Cleared: The diff only changes README prose and does not touch code execution, dependencies, secrets, CI, packaging, or supply-chain surfaces.

Review details

Best possible solution:

Merge the README sentence after normal maintainer review so the public quick-start guidance matches the existing callOnce no-OAuth behavior.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a docs-only PR; source inspection shows current main’s README still omits the disableOAuth guidance while runtime support and related docs already exist.

Is this the best way to solve the issue?

Yes. Updating the README callOnce paragraph is the narrowest maintainable fix because it aligns the recommended entry point with the already-merged runtime and CLI documentation.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3e27b64021c9.

Label changes

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body links the GitHub-rendered README section on the branch and copies the rendered updated paragraph, which is enough after-change proof for this README prose change.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (linked_artifact): The PR body links the GitHub-rendered README section on the branch and copies the rendered updated paragraph, which is enough after-change proof for this README prose change.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P3: This is a low-risk README clarification for an already-implemented headless OAuth option.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (linked_artifact): The PR body links the GitHub-rendered README section on the branch and copies the rendered updated paragraph, which is enough after-change proof for this README prose change.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body links the GitHub-rendered README section on the branch and copies the rendered updated paragraph, which is enough after-change proof for this README prose change.

Evidence reviewed

What I checked:

• Current README gap: Current main still describes callOnce as handling OAuth prompts for agent tool hooks without mentioning disableOAuth or --no-oauth. (README.md:257, 3e27b64021c9)
• PR diff is narrow: The branch changes only the callOnce README paragraph, adding the headless disableOAuth: true guidance and CLI flag cross-reference. (README.md:257, f3b8c4904451)
• Runtime supports the documented option: Current main’s callOnce parameter type includes disableOAuth?: boolean and forwards it into runtime.callTool. (src/runtime.ts:144, 3e27b64021c9)
• Existing docs already describe the same behavior: docs/mcp.md already tells headless callers they can pass disableOAuth: true to callOnce, and docs/cli-reference.md documents the matching --no-oauth flag wording. (docs/mcp.md:38, 3e27b64021c9)
• Regression coverage exists on main: The current test suite includes a forwards disableOAuth through callOnce case that verifies no OAuth provider is attached when disableOAuth: true is used. (tests/runtime-compose.test.ts:636, 3e27b64021c9)
• Feature history: Git history shows commit 3e27b64 added the disableOAuth runtime/docs/test surface, while the README callOnce paragraph still blames to the older v0.11.3 release commit. (src/runtime.ts:144, 3e27b64021c9)

Likely related people:

• feniix: Authored the merged disableOAuth follow-up area in commit 3e27b64, including callOnce forwarding, docs, and regression tests that this README change documents. (role: recent feature contributor; confidence: high; commits: 3e27b64021c9; files: src/runtime.ts, docs/mcp.md, docs/cli-reference.md)
• Peter Steinberger: The current README callOnce section and original callOnce helper blame to release commit 94e65ba before the later disableOAuth addition. (role: introduced README/runtime baseline; confidence: medium; commits: 94e65ba0572e; files: README.md, src/runtime.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[feniix]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27253046227
• Updated: 2026-06-10T04:28:01.036Z

[steipete]

Landed in c9325a6 after maintainer review.

Verification:

• Confirmed callOnce exposes and forwards disableOAuth.
• Confirmed the README wording matches the existing guidance in docs/mcp.md and the CLI --no-oauth documentation.
• Existing regression coverage verifies disableOAuth: true suppresses OAuth provider attachment.
• CI passed on Ubuntu, macOS, and Windows.

Thanks @feniix.