_meta keys follow the key-name grammar
A _meta key is an optional prefix of dot-separated labels ending in a slash, then a name that begins and ends with a letter or digit, for example com.example/feature-flag; keys outside that grammar may be ignored or rejected.
Check spec-meta-key · MCP specification 2026-07-28 · default severity: attention · rubric 2.1.0
What fails
A _meta key is an optional prefix (dot-separated labels, then a slash) and a name that begins and ends with a letter or digit. Keys outside the grammar may be ignored or rejected.
The rule
Labels MUST start with a letter and end with a letter or digit; interior characters can be letters, digits, or hyphens (
-).Source: MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons)
How to fix it
Rename the key, for example "com.example/feature-flag".
- Rename keys to prefix/name form: com.example/feature-flag.
- Each label starts with a letter and ends with a letter or digit; hyphens only inside.
- Keep MCP-reserved prefixes out (second label mcp or modelcontextprotocol).
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 },
_meta: { 'com.example/feature-flag': 'issues-v2' },
},
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),
meta={"com.example/feature-flag": "issues-v2"},
)
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 prefix required?
No, a bare name is allowed, but a reverse-DNS prefix you control avoids clashes with other software reading _meta.
What is _meta for?
Extension data that does not belong to the protocol fields: feature flags, UI hints, tracing ids. Clients that do not know a key ignore it.
Related checks
- _meta keys avoid prefixes reserved for MCP
- Tool fields have the types the schema defines
- Icon sources are https: or data: URIs
- All checks in MCP specification 2026-07-28: tools/list rules
How this check is graded
It counts toward: MCP specification 2026-07-28. See the rubric.
Last verified against MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons) 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