Skip to content
IsoKron

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 $ref values 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>".

  1. Copy the referenced schema into "$defs" at the root of inputSchema.
  2. Change each "$ref" to "#/$defs/<name>".
  3. Re-check that every local $ref resolves.

TypeScript SDK

TypeScript
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

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="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.

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