# _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. Last verified against MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons) on 2026-11-18.

## 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)](https://modelcontextprotocol.io/specification/2026-07-28/basic/index#_meta)

## How to fix it

Rename the key, for example "com.example/feature-flag".

1. Rename keys to prefix/name form: com.example/feature-flag.
2. Each label starts with a letter and ends with a letter or digit; hyphens only inside.
3. Keep MCP-reserved prefixes out (second label mcp or modelcontextprotocol).

### TypeScript SDK

```ts
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

```python
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"
```

## 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](https://isokron.ai/mcp-check/checks/spec-meta-reserved)
- [Tool fields have the types the schema defines](https://isokron.ai/mcp-check/checks/spec-field-types)
- [Icon sources are https: or data: URIs](https://isokron.ai/mcp-check/checks/spec-icon-scheme)
- [MCP specification 2026-07-28: tools/list rules](https://isokron.ai/mcp-check/checks/protocol)

Counts toward: MCP specification 2026-07-28.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
