docs: Document Claude Code command fix investigation by croakingtoad · Pull Request #688 · coleam00/Archon

croakingtoad · 2025-09-17T15:30:29Z

Summary

This PR documents the investigation into a reported error in the Claude Code MCP configuration command.

Issue Report

A user reported that the documentation at http://68.183.152.55:3737/mcp showed an incorrect Claude Code command:

claude mcp add --type http archon http://localhost:xxxx/mcp

The correct command should be:

claude mcp add --transport http archon http://localhost:xxxx/mcp

Investigation Results

After thorough investigation of the current codebase:

✅ All documentation files already use the correct --transport syntax

docs/docs/mcp-overview.mdx - Uses --transport sse (correct for SSE)
docs/docs/mcp-server.mdx - Uses --transport sse (correct for SSE)
archon-ui-main/src/features/mcp/components/McpConfigSection.tsx - Uses --transport http (correct for HTTP)

✅ No instances of --type http found in the main branch

Root Cause

The main branch already contains the correct syntax. The deployed instance showing the incorrect command may be running an older version of the code.

Resolution

This PR adds documentation of the investigation to help maintainers understand that:

The main branch is correct
Any deployed instances showing the wrong command need to be updated
The issue has already been resolved in the codebase

Files Added

docs/CLAUDE_CODE_COMMAND_FIX.md - Documents the investigation and current status

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

Summary by CodeRabbit

Documentation
- Added a guide clarifying the correct Claude Code command syntax.
- Highlights the incorrect flag previously seen (--type http) and the correct usage (--transport http).
- Confirms the main branch already uses the correct flag across relevant references.
- Provides guidance to update any deployments still using the older command.
- Recommends syncing deployments with the latest main branch to ensure consistency.

This documents the investigation into the reported Claude Code command error. The main branch already uses the correct --transport syntax instead of --type.

coderabbitai · 2025-09-17T15:30:37Z

Walkthrough

Adds a new documentation file clarifying correct Claude Code command usage, contrasting an incorrect flag (--type http) with the correct flag (--transport http), noting current repository status, listing checked files, and advising deployment updates to match main.

Changes

Cohort / File(s)	Summary
Documentation update `docs/CLAUDE_CODE_COMMAND_FIX.md`	New doc explaining correct Claude Code command flag (`--transport http`), highlighting previously reported incorrect usage (`--type http`), listing verified files, and advising deployments to sync with main.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

I twitch my ears at flags askew,
Hop-hop—now --transport carries through.
Burrows synced with main so neat,
No stray --type beneath my feet.
Carrots stacked, commands aligned—
A tidy warren, peace of mind.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "docs: Document Claude Code command fix investigation" is concise and directly reflects the primary change, which is adding documentation about an investigation into a Claude Code CLI syntax issue. It names the scope (docs) and the intent (documenting the command-fix investigation) without extraneous details, making it clear for reviewers scanning history. This matches the changeset that adds docs/CLAUDE_CODE_COMMAND_FIX.md and therefore meets the repository's title guidelines.
Description Check	✅ Passed	The PR description clearly documents the summary, the reported issue, investigation results, root cause, resolution, and the added file, so the substantive information reviewers need for a documentation-only change is present. It does not strictly follow the repository template: it lacks an explicit "Changes Made" bullet list, the "Type of Change" checkbox (e.g., Documentation update), "Affected Services" selection, and testing/test evidence checklist items. Because the core details are complete and specific, this check passes but the missing template fields should be added for process consistency.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (5)

docs/CLAUDE_CODE_COMMAND_FIX.md (5)
21-23: Avoid fragile “Line N” references; they drift.

Drop line numbers or replace with commit permalinks to prevent staleness.

Apply this diff:
-1. **docs/docs/mcp-overview.mdx** - Line 81: Uses `--transport sse` (correct for SSE)
-2. **docs/docs/mcp-server.mdx** - Line 99: Uses `--transport sse` (correct for SSE)
-3. **archon-ui-main/src/features/mcp/components/McpConfigSection.tsx** - Line 191: Uses `--transport http` (correct for HTTP)
+1. **docs/docs/mcp-overview.mdx**: Uses `--transport sse` (correct for SSE)
+2. **docs/docs/mcp-server.mdx**: Uses `--transport sse` (correct for SSE)
+3. **archon-ui-main/src/features/mcp/components/McpConfigSection.tsx**: Uses `--transport http` (correct for HTTP)
26-26: Remove/anonymize the bare IP; also fixes markdownlint MD034.

Public IPs in docs can leak infra details and violate “no-bare-urls”.

Apply this diff:
-The main branch already contains the correct syntax. If the deployed instance at http://68.183.152.55:3737/mcp is showing the incorrect command, it may be running an older version of the code that needs to be updated.
+The main branch already contains the correct syntax. If a deployed instance is showing the incorrect command, it may be running an older version of the code that needs to be updated.
Optionally add a generic placeholder elsewhere (e.g., <http://YOUR_HOST:PORT/mcp>).

18-23: Add “Last verified” and a local verification snippet.

Helps future readers validate claims quickly and keep this doc evergreen.

Apply this diff:
 After investigation of the current codebase, all instances of the Claude Code command in the repository already use the correct `--transport http` syntax:
 
+> Last verified: 2025-09-17 against `main`.
+
 1. **docs/docs/mcp-overview.mdx**: Uses `--transport sse` (correct for SSE)
 2. **docs/docs/mcp-server.mdx**: Uses `--transport sse` (correct for SSE)
 3. **archon-ui-main/src/features/mcp/components/McpConfigSection.tsx**: Uses `--transport http` (correct for HTTP)
 
 ## Resolution
@@
 - ✅ No instances of `--type http` found in the codebase
+
+## How to verify locally
+```sh
+rg -n --hidden -S --glob '!.git' -e '\b--type\s+(http|sse)\b' -e '\b--transport\s+(http|sse)\b'
+```
+Expect: zero matches for `--type http` or `--type sse`; matches should use `--transport`.
Also applies to: 29-31

1-4: If this should appear on the docs site, add Docusaurus frontmatter/move file.

If published via Docusaurus (repo uses docs/docs/), move this into docs/docs/ and add frontmatter; otherwise keep as internal root‑level doc.

Suggested frontmatter:
---
title: Claude Code command fix investigation
slug: claude-code-command-fix
sidebar_position: 999
---
33-34: Optional: add a CI guard to prevent regressions.

Fail PRs that reintroduce --type http.

Add a lightweight step:
- name: Guard against deprecated Claude MCP flags
  run: |
    rg -n --hidden -S --glob '!.git' '\b--type\s+http\b' && { echo "Found deprecated flag --type http"; exit 1; } || true

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b383c8c and b56570e.

📒 Files selected for processing (1)

docs/CLAUDE_CODE_COMMAND_FIX.md (1 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.17.2)

docs/CLAUDE_CODE_COMMAND_FIX.md

26-26: Bare URL used

(MD034, no-bare-urls)

🔇 Additional comments (1)

docs/CLAUDE_CODE_COMMAND_FIX.md (1)

1-17: Clear, useful incident write‑up.

The problem statement, incorrect vs. correct command, and remediation are concise and accurate. Nice.

leex279 · 2025-09-17T18:18:29Z

hey, thanks for the PR. Which issue/report you refering too? I dont see anything linked. Other than that I dont think we should do additional documentation for such stuff, cause the UI (as you state) already shows the correct commands and the users can just copy it from there.
The only thing I want to change in the UI is for external hosts, so the copy command will than contain the actual configured host instead of localhost.

Wirasm · 2025-09-18T10:18:43Z

Thank you for this PR
The solution you are proposing is incorrect and the current solution we have is the correct one

* feat: add per-node MCP servers for DAG workflows (#445) Add `mcp: path/to/config.json` field to DAG workflow nodes. At execution time, the executor reads the MCP config JSON, expands $VAR_NAME env references in env/headers values, and passes the loaded servers to the Claude Agent SDK via Options.mcpServers. MCP tool wildcards are auto- added to allowedTools. - Add mcp field to DagNodeBase type and loader validation - Add mcpServers + allowedTools to WorkflowAssistantOptions and AssistantRequestOptions - Pass mcpServers/allowedTools through ClaudeClient to SDK Options - Handle system/init message to detect MCP connection failures - Add Codex warning (per-node MCP not supported) - Add Haiku warning (tool search not supported) - Add MCP config path input in Web UI NodeInspector - Add mcp to WorkflowCanvas reactFlowToDagNodes conversion - Add 12 unit tests for loadMcpConfig and env var expansion * fix: address review findings for per-node MCP servers Type safety: - Use SDK McpServerConfig type in AssistantRequestOptions (eliminates unsafe cast) - Update WorkflowAssistantOptions.mcpServers to proper discriminated union - Remove redundant cast in claude.ts Error handling: - Warn users when MCP config references undefined env vars - Check safeSendMessage return value for MCP connection failures - Check safeSendMessage return value for Haiku MCP warning - Log unhandled system messages at debug level in both claude.ts and dag-executor.ts - Coerce non-string env/header values with warning instead of silent passthrough Code quality: - Fix log event naming: dag_node_mcp_* → dag.mcp_* (domain.action_state format) - Replace IIFE in loader mcp validation with plain if/else - Extract duplicated env expansion logic into expandEnvVarsInRecord helper - Merge split import from ./deps into single statement - Return missingVars from loadMcpConfig/expandEnvVars for caller awareness Documentation: - Add mcp field to Node Fields table in docs/authoring-workflows.md - Add mcp to DAG schema example, allowed_tools section, and summary list - Add mcp to CLAUDE.md DAG feature list - Add per-node MCP servers paragraph to README.md tool restrictions section * docs: add MCP servers guide (docs/mcp-servers.md) Comprehensive guide covering config file format (stdio/HTTP/SSE), env var expansion, automatic tool wildcards, MCP-only nodes, connection failure handling, workflow examples, troubleshooting, and popular server list. Cross-referenced from authoring-workflows.md and CLAUDE.md. * feat: add optional ntfy push notification to smart PR review Add conditional notify node to archon-smart-pr-review workflow that sends a push notification when the review completes. Gated behind a bash node that checks for .archon/mcp/ntfy.json — silently skipped if not configured. - Add check-ntfy bash node + notify MCP node to smart PR review workflow - Add .archon/mcp/ to .gitignore (per-user MCP configs may contain secrets) - Add "Push Notifications" setup guide to docs/mcp-servers.md

…am00#688) * feat: add per-node MCP servers for DAG workflows (coleam00#445) Add `mcp: path/to/config.json` field to DAG workflow nodes. At execution time, the executor reads the MCP config JSON, expands $VAR_NAME env references in env/headers values, and passes the loaded servers to the Claude Agent SDK via Options.mcpServers. MCP tool wildcards are auto- added to allowedTools. - Add mcp field to DagNodeBase type and loader validation - Add mcpServers + allowedTools to WorkflowAssistantOptions and AssistantRequestOptions - Pass mcpServers/allowedTools through ClaudeClient to SDK Options - Handle system/init message to detect MCP connection failures - Add Codex warning (per-node MCP not supported) - Add Haiku warning (tool search not supported) - Add MCP config path input in Web UI NodeInspector - Add mcp to WorkflowCanvas reactFlowToDagNodes conversion - Add 12 unit tests for loadMcpConfig and env var expansion * fix: address review findings for per-node MCP servers Type safety: - Use SDK McpServerConfig type in AssistantRequestOptions (eliminates unsafe cast) - Update WorkflowAssistantOptions.mcpServers to proper discriminated union - Remove redundant cast in claude.ts Error handling: - Warn users when MCP config references undefined env vars - Check safeSendMessage return value for MCP connection failures - Check safeSendMessage return value for Haiku MCP warning - Log unhandled system messages at debug level in both claude.ts and dag-executor.ts - Coerce non-string env/header values with warning instead of silent passthrough Code quality: - Fix log event naming: dag_node_mcp_* → dag.mcp_* (domain.action_state format) - Replace IIFE in loader mcp validation with plain if/else - Extract duplicated env expansion logic into expandEnvVarsInRecord helper - Merge split import from ./deps into single statement - Return missingVars from loadMcpConfig/expandEnvVars for caller awareness Documentation: - Add mcp field to Node Fields table in docs/authoring-workflows.md - Add mcp to DAG schema example, allowed_tools section, and summary list - Add mcp to CLAUDE.md DAG feature list - Add per-node MCP servers paragraph to README.md tool restrictions section * docs: add MCP servers guide (docs/mcp-servers.md) Comprehensive guide covering config file format (stdio/HTTP/SSE), env var expansion, automatic tool wildcards, MCP-only nodes, connection failure handling, workflow examples, troubleshooting, and popular server list. Cross-referenced from authoring-workflows.md and CLAUDE.md. * feat: add optional ntfy push notification to smart PR review Add conditional notify node to archon-smart-pr-review workflow that sends a push notification when the review completes. Gated behind a bash node that checks for .archon/mcp/ntfy.json — silently skipped if not configured. - Add check-ntfy bash node + notify MCP node to smart PR review workflow - Add .archon/mcp/ to .gitignore (per-user MCP configs may contain secrets) - Add "Push Notifications" setup guide to docs/mcp-servers.md

docs: Add documentation about Claude Code command fix

b56570e

This documents the investigation into the reported Claude Code command error. The main branch already uses the correct --transport syntax instead of --type.

coderabbitai Bot reviewed Sep 17, 2025

View reviewed changes

Wirasm closed this Sep 18, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Document Claude Code command fix investigation#688

docs: Document Claude Code command fix investigation#688
croakingtoad wants to merge 1 commit into
coleam00:mainfrom
croakingtoad:fix-claude-code-command-docs

croakingtoad commented Sep 17, 2025 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Sep 17, 2025 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

leex279 commented Sep 17, 2025

Uh oh!

Wirasm commented Sep 18, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

croakingtoad commented Sep 17, 2025 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Issue Report

Investigation Results

Root Cause

Resolution

Files Added

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Pre-merge checks and finishing touches

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

leex279 commented Sep 17, 2025

Uh oh!

Wirasm commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

croakingtoad commented Sep 17, 2025 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Sep 17, 2025 •

edited

Loading

Wirasm commented Sep 18, 2025 •

edited

Loading