Adding Custom MCP Server Metadata and Descriptions in Python

You add custom MCP server metadata and descriptions by passing description, version, and metadata parameters to the FastMCP constructor for server-level data, and by using the metadata dictionary in the @mcp.tool decorator for tool-level details.

The cr2007/mcp-wordle-python repository demonstrates how to enrich a minimal MCP server with human-readable metadata using the FastMCP framework. In src/mcp_wordle/main.py, the server instance and tool decorators are configured to expose descriptive information that appears in the MCP catalogue and client UIs like Claude Desktop.

Understanding MCP Server Metadata Architecture

MCP servers built with FastMCP support metadata at two distinct levels. Server-level metadata defines global properties such as the server name, description, and version, while tool-level metadata provides granular details about individual capabilities, including authorship, licensing, and usage examples.

In src/mcp_wordle/main.py, the FastMCP instance is initialized at lines 13‑14, and tools are registered via the decorator pattern at lines 30‑38. Both locations accept dictionaries that propagate to the MCP protocol’s ServerCapabilities and Tool objects.

Adding Server-Wide Metadata in FastMCP

Basic Server Configuration

To add a description, version, and custom metadata fields to your MCP server, modify the FastMCP constructor in src/mcp_wordle/main.py:

# Before: minimal initialization

mcp = FastMCP("WordleMCP")

# After: enriched with metadata

mcp = FastMCP(
    "WordleMCP",
    description="Provides Wordle puzzle solutions for a given date via the NYT API",
    version="0.1.0",
    metadata={
        "author": "Chandrashekhar R",
        "repository": "https://github.com/cr2007/mcp-wordle-python",
        "license": "MIT",
    },
)

Effect: When a client such as Claude Desktop connects to the server, the MCP catalogue now displays the human-readable description, version string, and the additional metadata fields, allowing users to identify the server’s purpose and provenance before invoking any tools.

Enriching Tool Definitions with Custom Metadata

Tool Decorator Parameters

Individual tools expose their own metadata through the @mcp.tool decorator. In src/mcp_wordle/main.py at lines 30‑38, the get_wordle_data function is registered with descriptive attributes:

@mcp.tool(
    name="get_wordle_solution",
    description=(
        "Fetches the Wordle solution for a specific date "
        "(range: 2021-05-19 to 23 days in the future)"
    ),
    annotations={"readOnlyHint": True},
    metadata={
        "author": "Chandrashekhar R",
        "license": "MIT",
        "tags": ["wordle", "puzzle", "nytimes", "game"],
        "example_input": {"target_date": "2024-12-01"},
        "rate_limit": "100 requests/day",
    },
)
async def get_wordle_data(target_date: str = date.today().isoformat()):
    ...

Key distinctions:

• description appears in tooltips and UI panels.
• annotations provide UI hints (e.g., readOnlyHint tells the client the tool does not modify state).
• metadata accepts arbitrary key-value pairs for documentation, tagging, or operational constraints.

Accessing Metadata Programmatically

If you need to expose the server’s metadata to clients dynamically, you can register a dedicated tool that returns the mcp instance’s internal dictionary:

@mcp.tool(name="server_metadata")
async def get_server_metadata() -> dict:
    """Return the server-level metadata defined at initialization."""
    return {
        "name": mcp.name,
        "description": mcp.description,
        "version": mcp.version,
        "metadata": mcp.metadata,
    }

This pattern is useful when building automated documentation generators or compliance dashboards that need to audit MCP server capabilities without parsing source code.

Summary

• Server metadata is defined in the FastMCP constructor at src/mcp_wordle/main.py lines 13‑14 using description, version, and the metadata dictionary.
• Tool metadata is supplied via the @mcp.tool decorator at lines 30‑38, supporting description, annotations, and custom metadata fields.
• FastMCP propagates these values to the MCP protocol, making them visible in client catalogues such as Claude Desktop.
• You can surface metadata programmatically by creating a tool that returns the server’s internal metadata dictionary.

Frequently Asked Questions

How do I add a description to an MCP server in Python?

Pass the description parameter to the FastMCP constructor in your main server file. In src/mcp_wordle/main.py, this is done at lines 13‑14: mcp = FastMCP("WordleMCP", description="Provides Wordle puzzle solutions..."). This string appears in the MCP catalogue and client UIs.

What is the difference between annotations and metadata in FastMCP tools?

Annotations are standardized UI hints defined by the MCP protocol, such as readOnlyHint or destructiveHint, which affect how clients display or handle the tool. Metadata is an arbitrary dictionary you can populate with any key-value pairs—such as author, license, or tags—for documentation, discovery, or operational purposes. Both are declared in the @mcp.tool decorator.

Can I expose MCP server metadata through a tool endpoint?

Yes. You can register a tool that returns the server’s metadata dictionary by accessing the FastMCP instance attributes. For example, create a tool named server_metadata that returns a dictionary containing mcp.name, mcp.description, mcp.version, and mcp.metadata. This allows clients to query capabilities dynamically without inspecting source code.

Where is server metadata defined in the Wordle MCP repository?

Server metadata is defined in src/mcp_wordle/main.py at lines 13‑14 within the FastMCP constructor. Tool-specific metadata is defined further down at lines 30‑38 inside the @mcp.tool decorator for the get_wordle_solution function. These locations control how the server and its tools are presented in MCP clients.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}