MCPB should include static server instructions

[asklar]

There is a "server instructions" as part of initializing the connection: https://modelcontextprotocol.io/specification/2025-06-18/schema#initializeresult-instructions

It would be useful for MCPB descriptions to have a static version of this.

Proposal

{
  "$schema": "../../dist/mcpb-manifest.schema.json",
  "manifest_version": "0.1",
  "name": "hello-world-node",
  "display_name": "Hello World MCP Server (Reference Extension)",
  "version": "0.1.0",
  "description": "A reference MCP extension demonstrating best practices and all available features",
  "long_description": "This is a reference implementation of a MCP Bundle (DXT). It demonstrates all available manifest features, user configuration options, and security best practices. Use this extension as a template when creating your own MCP servers. The extension includes examples of all user configuration types, proper request token verification, and comprehensive metadata fields.",
  "author": {
    "name": "Acme Inc",
    "email": "support@acme.void",
    "url": "https://www.acme.void"
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node"
    }
  },
  "tools": [
    {
      "name": "get_current_time",
      "description": "Get the current computer time in various formats"
    }
  ],
  "instructions": "Use this server to get the current time" // NEW FIELD -- can be long
}

[joan-anthropic]

hi @asklar ! I think the original idea was that long_description could be used to include server instructions if-needed, from the spec:

A detailed description that can include multiple paragraphs explaining the extension's functionality, use cases, and features.

What would the use case for a standalone "instructions" be?

[asklar]

today instructions are defined as:

Instructions describing how to use the server and its features.
This can be used by clients to improve the LLM’s understanding of available tools, resources, etc. It can be thought of like a “hint” to the model. For example, this information MAY be added to the system prompt.

So there's an expectation that instructions could end up in the system prompt - long description doesn't have that.

Examples of instructions:
https://github.com/opentofu/opentofu-mcp-server/blob/f2a4bef833ea46367f5c85377da7b5c2c21df9e9/src/servers/registry/index.ts#L37-L49

They aren't quite a description, e.g. see the callout to use other servers. The instructions are intended as behavioral directives for the model to follow, rather than a description of the server itself. Compare these instructions with something like "This server is useful for getting the weather forecast...".
At the end of the day it's all text :) But the expectations of what each field is used for, matter.
A reasonable outcome of this could be to add "long_description is to be used to statically declare instructions for the model" (or something like that) to the MCPB spec.

[joan-anthropic]

Thanks for the context! Can you share why a static representation in manifest.json would be useful? I think the main concern here is that we'd be duplicating content that the developer defines in the MCP server itself (potential for divergent sources-of-truth + increased developer friction)

[asklar]

Right, the rationale is to avoid running untrusted code until the user says something that should trigger a server/tool and the model chooses to call it (see this comment for a similar discussion).

If a server's runtime behavior doesn't match its static declaration, clients are advised to terminate their connection to the server.

[asklar]

We discussed this offline - this will for now be part of the new _meta property and specifically be scoped to Windows's implementation. Windows docs will follow on final guidance.
Keeping this open for when we want to promote this to a standard property instead of _meta. See #122 too.