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

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

## 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

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

## 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](https://isokron.ai/mcp-check/checks/spec-schema-valid)
- [Schema depth and size stay within common validator bounds](https://isokron.ai/mcp-check/checks/spec-composition-bounds)
- [Schemas use JSON Schema 2020-12](https://isokron.ai/mcp-check/checks/spec-schema-dialect)
- [MCP tool input and output schemas](https://isokron.ai/mcp-check/checks/schema)

Counts toward: MCP specification 2026-07-28.

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

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