Skip to content

fix(mcp): Claude Code compatible tool names via transformer#3121

Merged
amitksingh1490 merged 5 commits intomainfrom
claude-code-compatibility
Apr 22, 2026
Merged

fix(mcp): Claude Code compatible tool names via transformer#3121
amitksingh1490 merged 5 commits intomainfrom
claude-code-compatibility

Conversation

@amitksingh1490
Copy link
Copy Markdown
Contributor

@amitksingh1490 amitksingh1490 commented Apr 22, 2026

Summary

Make MCP tools work with Claude Code's mcp__{server}__{tool} naming convention while preserving Forge's internal legacy MCP registration format and backward-compatible execution behavior.

Context

Claude Code expects MCP tool names to use double underscores between the mcp prefix, server name, and tool name. Forge internally stores MCP tools using the legacy mcp_{server}_tool_{tool} format, and a direct rename would have rippled through registration, lookup, and existing agent behavior. This change bridges the two formats so Claude Code compatibility is added without forcing an internal migration.

Changes

  • Added an Anthropic request transformer that rewrites outbound MCP tool names from Forge's internal legacy format to Claude Code's expected format
  • Kept MCP tools registered internally using the legacy _tool_ separator format for compatibility with existing lookup and storage behavior
  • Added reverse normalization so incoming Claude Code tool calls are converted back to Forge's internal format before MCP lookup and execution
  • Centralized MCP tool name generation in the service layer and expanded coverage for multipart server names and _tool_ edge cases
  • Wired the new transform into the Claude Code / OAuth Anthropic pipeline
  • Updated the MCP tool description text to explain the outbound conversion and inbound normalization behavior

Key Implementation Details

The compatibility layer is intentionally asymmetric:

  • outbound provider requests convert mcp_{server}_tool_{tool} to mcp__{server}__{tool}
  • inbound tool calls from Claude Code are normalized back to the legacy format before lookup
  • internal MCP registration, caching, and execution continue using the legacy format

The name conversion logic uses the last _tool_ separator so server names that themselves contain _tool_ are still parsed correctly.

Use Cases

  • Claude Code can discover Forge MCP tools using the naming format it expects
  • Existing Forge MCP execution paths continue to work without migrating stored or generated internal tool names
  • MCP servers with multipart or underscored names remain addressable in both directions

Testing

cargo build
cargo test -p forge_app mcp_tool_names --lib
forge mcp reload
cargo build

@github-actions github-actions Bot added the type: refactor Code refactoring and restructuring. label Apr 22, 2026
@amitksingh1490 amitksingh1490 changed the title refactor(mcp): standardize tool name format with double underscore separator refactor(mcp): standardize tool name format to mcp__{server}__{tool} Apr 22, 2026
@amitksingh1490 amitksingh1490 changed the title refactor(mcp): standardize tool name format to mcp__{server}__{tool} feat(mcp): Claude Code compatible tool names via transformer Apr 22, 2026
Convert MCP tool names between internal legacy format (`mcp_{server}_tool_{tool}`) and Claude Code format (`mcp__{server}__{tool}`) for OAuth-authenticated sessions. Add bidirectional conversion utilities to support both naming conventions in tool discovery and execution.
@github-actions github-actions Bot added the type: feature Brand new functionality, features, pages, workflows, endpoints, etc. label Apr 22, 2026
@amitksingh1490 amitksingh1490 merged commit 513e96f into main Apr 22, 2026
8 checks passed
@amitksingh1490 amitksingh1490 deleted the claude-code-compatibility branch April 22, 2026 12:24
@amitksingh1490 amitksingh1490 changed the title feat(mcp): Claude Code compatible tool names via transformer fix(mcp): Claude Code compatible tool names via transformer Apr 22, 2026
@amitksingh1490 amitksingh1490 added type: fix Iterations on existing features or infrastructure. and removed type: feature Brand new functionality, features, pages, workflows, endpoints, etc. type: refactor Code refactoring and restructuring. labels Apr 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: fix Iterations on existing features or infrastructure.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant