MCP server instructions - give LLMs more context on your MCP server

In our previous article on MCP evals, we discussed techniques to improve "tool ergonomics", designing an MCP server such that an LLM can understand how to use it. One of the most underutilized methods to improve tool ergonomics is writing MCP server instructions.

Server instructions in the MCP spec is a dedicated mechanism for servers to provide LLMs with essential contextual knowledge like tool interdependencies and operational constraints. MCP server instructions were introduced since the initial launch of MCP, but it didn't gain much awareness until Ola's (core maintainer) blog earlier this month.

Current MCP clients that support MCP server instructions include Claude Code, VSCode, and Goose, with hopefully more to come. Writing server instructions can drastically improve your MCP server's experience. Let's take a look at best practices for how to write server instructions.

How MCP clients load and use server instructions

Clients load a MCP server's instructions on the initial connection step. The client sends an initialization request to the server to initiate the connection:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": "",
    "capabilities": {
      "elicitation": {}
    },
    "clientInfo": {
      "name": "hf",
      "version": "1.0.0"
    }
  }
}

The MCP server sends a response message with the MCP server instructions in its body. Here's an example of what the Hugging Face MCP server responds with.

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {
        "listChanged": false
      },
      "prompts": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "@huggingface/mcp-services",
      "version": "0.2.51",
      "title": "Hugging Face",
      "websiteUrl": "https://huggingface.co/mcp",
      "icons": [
        {
          "src": "https://huggingface.co/favicon.ico"
        }
      ]
    },
    "instructions": "You have tools for searching the Hugging Face Hub..."
  }
}

The MCP spec doesn't specify exactly how MCP clients should handle server instructions, it's up to the client implementor to decide what to do with a server instruction. What clients most likely are doing is injecting the server instructions into the LLM context as system prompts / LLM instructions.

Writing good server instructions

Server instructions should be concise, focused documentation that helps the LLM understand:

1. What the server does - Brief overview
2. Key capabilities - Main features and tools
3. Important constraints - Limitations or requirements
4. Usage patterns - How tools/resources work together
5. Performance characteristics - Behavior expectations

What MCP server instructions should do:

• Keep it concise and scannable
• Use clear section headers
• Explain patterns and conventions
• Document dependencies between features
• Note performance/timing expectations
• Include practical usage hints

DO NOT DO:

• Duplicate tool descriptions. Those belong in the tool schemas
• Write verbose explanations
• Include implementation details
• Add marketing content
• Repeat information available elsewhere

Examples

Here's Huggingface's MCP server instructions:

You have tools for searching the Hugging Face Hub. arXiv paper id's
are often used as references between datasets, models and papers.
There are over 100 tags in use, common tags include 'Text Generation',
'Transformers', 'Image Classification' and so on.

The User has access to 'Prompts' that provide ways to summarise
various types of Hugging Face hub content, and you may guide them to
check this feature. The Hugging Face tools are being used anonymously
and rate limits apply. Direct the User to set their HF_TOKEN
(instructions at https://hf.co/settings/mcp/), or create an account
at https://hf.co/join for higher limits.

Huggingface's server instructions are verbose, do not have tool-specific instructions, and give context to the LLM on the server at a high level.

Server instructions template

Here's a template to write MCP server instructions:

[Server Name] - [One-line purpose]

## Key Capabilities

[Brief list of main features]

## Usage Patterns

[How tools/resources work together]

## Important Notes

[Critical constraints or requirements]

## Performance

[Expected behavior, timing, limits]

View server instructions in MCPJam

We built support in the MCPJam inspector to view your MCP server's instructions, and other server metadata like icons, version, capabilities, and ChatGPT apps widget metadata.

Starting up MCPJam inspector is a single npx command:

npx -y @mcpjam/inspector@latest