Skip to content

feat: make the Claude gateway URL configurable - #63

Open
teallarson wants to merge 2 commits into
fix/claude-directory-compliancefrom
codex/claude-configurable-gateway
Open

teallarson wants to merge 2 commits into
fix/claude-directory-compliancefrom
codex/claude-configurable-gateway

Conversation

@teallarson

@teallarson teallarson commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

What/why

Claude Code users can set Arcade gateway URL in /config to connect the plugin to their own Arcade gateway. Leaving the setting unset uses https://api.arcade.dev/mcp/arcade. A failed custom connection does not silently switch to the default.

Codebase changes

  • Generate Claude's userConfig.gateway_url setting with its default from plugin/mcp.json.
  • Update routing instructions and setup documentation for custom endpoints.
  • Check the configured URL's default in directory validation and installation verification.

Additional notes

Based on #62.

Measured validation:

  • npm run verify: 217 tests passed, 2 skipped; Claude, Cursor, Codex, and Copilot checks passed.
  • An isolated Claude Code 2.1.304 installation selected the default URL without a setting, then selected the custom URL after configuration. An unavailable custom endpoint reported a connection error and stayed selected.
  • Independent review found no actionable issues. Claude Desktop and Cowork remain untested.

— Strider 🐦‍⬛, Teal's agent


Note

Medium Risk
Changes how Claude connects to MCP (user-supplied HTTPS endpoints) and tightens manifest/validation around those defaults; other clients and core app code are largely unaffected but misconfiguration could break the gateway connection.

Overview
Claude Code can point the plugin at a custom Arcade MCP gateway via a new Arcade gateway URL setting in /config, while the public default stays https://api.arcade.dev/mcp/arcade.

Manifest generation now adds userConfig.gateway_url (default taken from plugin/mcp.json) and wires Claude’s mcpServers.arcade.url to ${user_config.gateway_url}; Cursor and the portable mcp.json keep the literal endpoint. Docs and regenerated routing text tell agents to use the configured endpoint when set, and the README notes that a bad custom URL does not fall back to the default.

Directory policy, install verification, and tests resolve ${user_config.*} URLs through defaultMcpUrl and require an HTTPS default for directory submission.

Reviewed by Cursor Bugbot for commit a1adeaa. Bugbot is set up for automated code reviews on this repo. Configure here.

teallarson and others added 2 commits November 20, 2026 10:42
…gateway

Both Claude manifests (plugin/ with hooks, clients/claude/ without) now
get the gateway_url setting.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@teallarson
teallarson marked this pull request as ready for review November 20, 2026 19:31

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit a1adeaa. Configure here.

};
// Claude uses "http" for the "streamable-http" transport in mcp.json.
const claudeMcpServers = { arcade: { type: "http", url } };
const claudeMcpServers = { arcade: { type: "http", url: "${user_config.gateway_url}" } };

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Chat ignores configurable gateway URL

High Severity

Both Claude manifests now set mcpServers.arcade.url to ${user_config.gateway_url}. Claude's platform support ignores plugin MCP servers in Chat when the URL contains ${user_config.*}, so Desktop and claude.ai installs lose the Arcade gateway. Only Claude Code prompts for the setting.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit a1adeaa. Configure here.

@teallarson teallarson Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@cursoragent but Claude lets you configure this in the UI.... The UX is quite odd.

@cursor cursor Bot Nov 20, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Bugbot finding is accurate, and your reply doesn't resolve it. I didn't change anything or reply on the PR.

  • Claude's platform table (claude.com/docs/plugins/platform-support) says an MCP server whose URL contains ${user_config.*} is ignored in Chat. In Cowork it's ignored when the referenced option has no default. Claude Code loads it and prompts for the value. This PR gives the option a default, so Cowork should load the default URL. Chat is the problem.
  • The UI point is partly right. Claude Code's /config is the UI for this setting, and Chat users can add a custom connector under Settings → Connectors. The "Tools only" section of docs/install/claude-desktop.md already describes that. But it doesn't cover the plugin's tools in Chat. Those servers are dropped silently, and docs/install/claude-desktop.md still says "Chat gets tools and skills."
  • Desktop Code has a related issue. Claude's tracker has an open bug ([BUG] Desktop Code: cannot sign in to a plugin MCP server whose URL uses ${user_config.*} anthropics/claude-code#108574) where sign-in fails for plugin MCP servers whose URL uses ${user_config.*}.

You need to pick a trade-off, because one plugin manifest can't both substitute the setting in Claude Code and keep a literal URL for Chat:

  1. Keep the setting and document the gap. Claude Code gets /config. Chat users add the connector by hand, and the Desktop docs say the plugin's tools aren't available in Chat.
  2. Use a literal default URL in the Claude manifest. Chat, Cowork, and Desktop Code all load the gateway. The /config setting goes away, and a custom gateway in Claude Code needs another path.

I'd lean toward option 2 unless custom gateways in Claude Code are a hard requirement. Tell me which you want and I'll make the change, update the docs and tests, and push to this branch.

Open in Web Open in Cursor 

@teallarson teallarson Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes but you can set it in the plugin under "Connector" in Claude Desktop.

This branch has not been deployed

No deployments
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