No $ref to a network or external URI
MCP implementations MUST NOT dereference a $ref that resolves to a network URI, so a tool schema that points at an external schema loses that part; inline it under $defs and use "#/$defs/<name>".
Check spec-ref-remote · MCP specification 2026-07-28 · default severity: attention · rubric 2.1.0
What fails
Clients will not fetch the referenced schema, and the specification says schemas that fail on an unresolved external $ref SHOULD be rejected. The tool may be dropped or its arguments left unchecked.
The rule
Implementations MUST NOT automatically dereference
$refvalues that resolve to a network URI.Source: MCP specification 2026-07-28: Overview (JSON Schema usage, _meta, icons)
How to fix it
Inline the referenced schema under $defs and point the $ref at "#/$defs/<name>".
- Copy the referenced schema into "$defs" at the root of inputSchema.
- Change each "$ref" to "#/$defs/<name>".
- Re-check that every local $ref resolves.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'create_contact',
{
title: 'Create contact',
description: 'Create one contact. Use when the user asks to add a person to the address book.',
inputSchema: z.strictObject({
full_name: z.string().describe('Full name'),
email: z.string().describe('Email address'),
}),
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
},
async ({ full_name, email }) => ({ 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="Create contact",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False),
)
def create_contact(
full_name: Annotated[str, Field(description="Full name")],
email: Annotated[str, Field(description="Email address")],
) -> str:
"""Create one contact. Use when the user asks to add a person to the address book."""
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
Why not just fetch the remote schema?
Fetching schemas at call time lets whoever controls that URL change what a tool accepts after review, and makes clients depend on the network. The specification forbids it.
Do SDKs emit $ref?
Generators emit local $refs into $defs for shared or recursive types, which is fine. Remote references come from hand-written or converted schemas.
Related checks
- inputSchema and outputSchema are valid JSON Schema
- Schema depth and size stay within common validator bounds
- Schemas use JSON Schema 2020-12
- All checks in MCP tool input and output schemas
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