Skip to content

fix: clarify localhost connector instructions in serve output#4

Open
cstirry wants to merge 1 commit into
mainfrom
bugfix/serve-localhost-connector-instructions
Open

fix: clarify localhost connector instructions in serve output#4
cstirry wants to merge 1 commit into
mainfrom
bugfix/serve-localhost-connector-instructions

Conversation

@cstirry
Copy link
Copy Markdown

@cstirry cstirry commented May 8, 2026

Problem

When running uv run opencontext serve, the output includes instructions to connect via Claude Connectors using the localhost URL:

==================================================
Connect via Claude Connectors
==================================================

1. Go to Settings -> Connectors (or Customize -> Connectors on claude.ai)
2. Click 'Add custom connector'
3. Enter a name (govex---dc-opendata) and URL: http://localhost:8000/mcp

Note: Localhost works with Claude Desktop only (web needs a deployed URL).

This is misleading on two counts:

  1. The note says "Localhost works with Claude Desktop" — it does not. Claude Desktop also rejects plain http:// localhost URLs.
  2. The instructions walk the user through adding a connector that will not work, with no clear path to fix it.

How to reproduce the original issue

  1. Run uv run opencontext serve
  2. Follow the connector instructions using http://localhost:8000/mcp
  3. Claude Desktop rejects the URL with a red error indicator
  4. claude.ai also rejects it — a public https:// URL is required for both

What's fixed

Restructured the output to:

  • Lead with the curl/test commands which actually work locally
  • Remove the misleading step-by-step connector instructions for localhost
  • Add a clear note that a deployed https:// URL is required to connect to Claude, with a pointer to opencontext deploy

What it looks like now

==================================================
Local MCP Server running!
==================================================
URL: http://localhost:8000/mcp

==================================================
Test with:
==================================================

  opencontext test --url http://localhost:8000/mcp
  or curl -X POST http://localhost:8000/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

==================================================
Connect via Claude Connectors
==================================================

To connect to Claude, a public https:// URL is required.
Run 'opencontext deploy --env staging' to get a deployed URL,
then add it as a custom connector in Claude settings.

Press Ctrl+C to stop
==================================================

Files changed

  • cli/commands/serve.py

@cstirry cstirry marked this pull request as ready for review May 8, 2026 20:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant