Reference implementation for SEP-2417: Model Preferences for Tools — a proposal to add modelPreferences to MCP tool annotations, allowing servers to signal what model capability level best suits each tool.

This server exposes three tools with different complexity profiles. Each tool includes model preference hints via _meta on the tool definition, so clients can see preferences at discovery time (tools/list) — before calling any tool:

A client calling tools/list sees the full preference profile for every tool upfront, enabling proactive model routing without calling any tools first.

npm install
npm start

The server uses stdio transport. Connect with the MCP Inspector or any MCP client.

The server uses registerTool() with _meta to attach model preferences to each tool definition:

server.registerTool("deep_analysis", {
  description: "Multi-dimensional analysis with evidence chains...",
  inputSchema: { subject: z.string(), depth: z.enum(["standard", "comprehensive"]).optional() },
  annotations: { readOnlyHint: true, openWorldHint: false },
  _meta: {
    "com.example/model-preferences": {
      intelligencePriority: 0.9,
      costPriority: 0.2,
      speedPriority: 0.3,
    },
  },
}, handler);

When a client calls tools/list, it receives:

{
  "tools": [
    {
      "name": "deep_analysis",
      "description": "...",
      "inputSchema": { "..." },
      "annotations": { "readOnlyHint": true, "openWorldHint": false },
      "_meta": {
        "com.example/model-preferences": {
          "intelligencePriority": 0.9,
          "costPriority": 0.2,
          "speedPriority": 0.3
        }
      }
    }
  ]
}

This demo uses _meta with a namespaced key because ToolAnnotations doesn't yet include modelPreferences. The SEP proposes adding it as a first-class annotation field:

Current (this demo) — via _meta on tool definition:

{
  "name": "deep_analysis",
  "_meta": {
    "com.example/model-preferences": {
      "intelligencePriority": 0.9,
      "costPriority": 0.2,
      "speedPriority": 0.3
    }
  }
}

Proposed (SEP) — via annotations:

{
  "name": "deep_analysis",
  "annotations": {
    "readOnlyHint": true,
    "modelPreferences": {
      "intelligencePriority": 0.9,
      "costPriority": 0.2,
      "speedPriority": 0.3
    }
  }
}

The modelPreferences type already exists in the MCP spec for sampling. This proposal reuses it for tool annotations — same dimensions (intelligence, cost, speed), same 0.0-1.0 scale.

MIT