Tool names are unique within the server
Tool names SHOULD be unique within an MCP server; with a duplicate, a call can reach either tool, clients keep one and drop the other, and the Claude API refuses a request that carries two tools of the same name.
Check spec-name-unique · MCP specification 2026-07-28 · default severity: attention · rubric 2.1.0
Error message you’ll see
tools: Tool names must be unique.Claude API (400), when two connected tools end up with the same name. Where this was reported
Tool […] is already registeredTypeScript SDK 2.4.0, registerTool with a name already in use. Where this message comes from
Tool already exists: […]Python SDK (mcp 2.3.0; a logged warning, the second registration is ignored). Where this message comes from
What fails
With two tools of the same name, a call can reach either one. Clients keep one and drop the other.
The rule
Tool names SHOULD be unique within a server.
How to fix it
Rename one of the tools, or remove the duplicate.
- Find the duplicated name in the list (generated tools from an OpenAPI spec are a common cause).
- Rename one tool so each name says what sets it apart, or remove the duplicate.
- Check the whole paginated list: duplicates can sit on different pages.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'get_issue',
{
title: 'Get issue',
description: 'Return one issue by ID. Use when the user names an issue.',
inputSchema: z.strictObject({
issue_id: z.string().describe('Issue ID, for example ISS-42'),
}),
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
},
async ({ issue_id }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="Get issue",
annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def get_issue(
issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
) -> str:
"""Return one issue by ID. Use when the user names an issue."""
return "Done"Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
Is a duplicate name an error or a warning?
The specification says SHOULD, so it is not a protocol error. In practice it fails: the TypeScript SDK throws "Tool ... is already registered", the Python SDK ignores the second tool, and the Claude API rejects requests with duplicate names. OpenAI makes uniqueness a requirement.
Do names have to be unique across servers?
No, only within one server. Clients prefix the server name to keep tools from different servers apart.
Related checks
- Tool names are unique within the server (ChatGPT)
- The paste holds the whole tool list
- Larger catalogs use a naming prefix
- All checks in MCP tool names
How this check is graded
It counts toward: MCP specification 2026-07-28. See the rubric.
Last verified against MCP specification 2026-07-28: Tools on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere