Skip to content

fix(validation): allow tool names starting with underscore or number#2534

Merged
crivetimihai merged 1 commit intomainfrom
2528-tool-name-starts-with-underscore
Jan 28, 2026
Merged

fix(validation): allow tool names starting with underscore or number#2534
crivetimihai merged 1 commit intomainfrom
2528-tool-name-starts-with-underscore

Conversation

@crivetimihai
Copy link
Copy Markdown
Member

@crivetimihai crivetimihai commented Jan 28, 2026 •
edited
Loading

Summary

Fixes the validation pattern for MCP tool names to align with SEP-986, which does not mandate that tool names must start with a letter.

  • Updated VALIDATION_TOOL_NAME_PATTERN from ^[a-zA-Z][a-zA-Z0-9._-]*$ to ^[a-zA-Z0-9_][a-zA-Z0-9._/-]*$
  • Tool names starting with underscore (e.g., _5gpt_query_by_market_id) or number (e.g., 123_tool) are now accepted
  • Tool names with slashes (e.g., namespace/subtool) are now accepted per SEP-986
  • Tool names starting with hyphen (e.g., -tool) remain invalid for safety
  • Removed / from HTML special characters regex (not XSS-relevant)

Files Changed

Core validation:

  • mcpgateway/config.py - Default pattern
  • mcpgateway/common/validators.py - Validation logic, error messages, HTML regex
  • mcpgateway/schemas.py - Pydantic schema docstrings
  • mcpgateway/utils/error_formatter.py - User-friendly error mapping

Configuration:

  • .env.example - Documented default
  • charts/mcp-stack/values.yaml - Helm chart default
  • charts/mcp-stack/README.md - Helm documentation

Tests:

  • tests/unit/mcpgateway/validation/test_validators.py
  • tests/unit/mcpgateway/validation/test_validators_advanced.py
  • tests/unit/mcpgateway/utils/test_error_formatter.py

Documentation:

  • docs/docs/testing/acceptance.md

Verification

Tested against running docker-compose deployment:

# Tool name starting with underscore - PASSES
curl -X POST localhost:8080/tools -d '{"tool": {"name": "_5gpt_query_by_market_id", ...}}'
# Returns 200 OK

# Tool name starting with number - PASSES  
curl -X POST localhost:8080/tools -d '{"tool": {"name": "123_numeric_tool", ...}}'
# Returns 200 OK

# Tool name with slash - PASSES (per SEP-986)
curl -X POST localhost:8080/tools -d '{"tool": {"name": "namespace/subtool", ...}}'
# Returns 200 OK

# Tool name starting with hyphen - CORRECTLY REJECTED
curl -X POST localhost:8080/tools -d '{"tool": {"name": "-invalid_tool", ...}}'
# Returns 422 with validation error

Closes #2528

@crivetimihai crivetimihai mentioned this pull request Jan 28, 2026
Closed
7 tasks
@crivetimihai crivetimihai force-pushed the 2528-tool-name-starts-with-underscore branch 2 times, most recently from 5a8d43b to 2fd8ccb Compare January 28, 2026 03:22
@crivetimihai @kevalmahajan
fix(validation): allow tool names starting with underscore or number
6522a87 
The MCP specification does not mandate that tool names must start with
a letter - tool names are simply strings without pattern restrictions.
This fix updates the validation pattern to align with SEP-986.

Changes:
- Update VALIDATION_TOOL_NAME_PATTERN from ^[a-zA-Z][a-zA-Z0-9._-]*$
  to ^[a-zA-Z0-9_][a-zA-Z0-9._/-]*$ per SEP-986
- Allow leading underscore/number and slashes in tool names
- Remove / from HTML special characters regex (not XSS-relevant)
- Update all error messages, docstrings, and documentation
- Update tests to verify new valid cases

Tool names like `_5gpt_query_by_market_id` and `namespace/tool` are
now accepted.

Closes #2528

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@kevalmahajan kevalmahajan force-pushed the 2528-tool-name-starts-with-underscore branch from 2fd8ccb to 6522a87 Compare January 28, 2026 10:27
@kevalmahajan kevalmahajan self-assigned this Jan 28, 2026
kevalmahajan
kevalmahajan approved these changes Jan 28, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@kevalmahajan kevalmahajan left a comment

Choose a reason for hiding this comment

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

Reviewed and tested the changes and verified them against the SEP-986 specification for MCP tool names.

  1. Regex Compliance: The updated regex ^[a-zA-Z0-9_][a-zA-Z0-9._/-]*$ correctly implements the SEP-986 standard:

    • Allows forward slashes / for namespacing.
    • Allows starting with valid characters (including numbers/underscores) that were previously restricted.
    • Excludes invalid starting characters like hyphens (correctly blocked).

  2. Shared Length Limit:

    • The code uses VALIDATION_MAX_NAME_LENGTH (default 255) for tool names.
    • While SEP-986 recommends a 64-character limit, using 255 is acceptable as a permissive gateway limit (it's a superset).
    • Note: Since this constant is shared with validate_display_name, validate_identifier, and validate_uri, changing it would have side effects. If strict 64-char enforcement is required for tool names later, we should introduce a dedicated VALIDATION_MAX_TOOL_NAME_LENGTH.

@crivetimihai crivetimihai merged commit aaf32fc into main Jan 28, 2026
53 checks passed
@crivetimihai crivetimihai deleted the 2528-tool-name-starts-with-underscore branch January 28, 2026 12:04
@crivetimihai crivetimihai added this to the Release 1.0.0-RC1 milestone Jan 31, 2026
hughhennelly pushed a commit to hughhennelly/mcp-context-forge that referenced this pull request Feb 8, 2026
@crivetimihai @hughhennelly
fix(validation): allow tool names starting with underscore or number (I…
915fbf6 
…BM#2534)

The MCP specification does not mandate that tool names must start with
a letter - tool names are simply strings without pattern restrictions.
This fix updates the validation pattern to align with SEP-986.

Changes:
- Update VALIDATION_TOOL_NAME_PATTERN from ^[a-zA-Z][a-zA-Z0-9._-]*$
  to ^[a-zA-Z0-9_][a-zA-Z0-9._/-]*$ per SEP-986
- Allow leading underscore/number and slashes in tool names
- Remove / from HTML special characters regex (not XSS-relevant)
- Update all error messages, docstrings, and documentation
- Update tests to verify new valid cases

Tool names like `_5gpt_query_by_market_id` and `namespace/tool` are
now accepted.

Closes IBM#2528

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
Signed-off-by: hughhennnelly <hughhennelly06@gmail.com>
kcostell06 pushed a commit to kcostell06/mcp-context-forge that referenced this pull request Feb 24, 2026
@crivetimihai
fix(validation): allow tool names starting with underscore or number (I…
8c7c730 
…BM#2534)

The MCP specification does not mandate that tool names must start with
a letter - tool names are simply strings without pattern restrictions.
This fix updates the validation pattern to align with SEP-986.

Changes:
- Update VALIDATION_TOOL_NAME_PATTERN from ^[a-zA-Z][a-zA-Z0-9._-]*$
  to ^[a-zA-Z0-9_][a-zA-Z0-9._/-]*$ per SEP-986
- Allow leading underscore/number and slashes in tool names
- Remove / from HTML special characters regex (not XSS-relevant)
- Update all error messages, docstrings, and documentation
- Update tests to verify new valid cases

Tool names like `_5gpt_query_by_market_id` and `namespace/tool` are
now accepted.

Closes IBM#2528

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kevalmahajan kevalmahajan kevalmahajan approved these changes

@madhav165 madhav165 Awaiting requested review from madhav165 madhav165 is a code owner

Assignees

@madhav165 madhav165

@kevalmahajan kevalmahajan

Labels

crimson

Projects

None yet

Milestone

Release 1.0.0-RC1

Development

Successfully merging this pull request may close these issues.

[BUG]: MCP Servers with tool name starts with "_" is failing to add to gateway

3 participants

@crivetimihai @kevalmahajan @madhav165