# Adding Custom MCP Server Metadata and Descriptions in Python

> Learn how to add custom MCP server metadata and descriptions using Python. Enhance your server configuration with detailed parameters and tool-level information.

- Repository: [CSK/mcp-wordle-python](https://github.com/cr2007/mcp-wordle-python)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/cr2007/mcp-wordle-python/blob/main/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`](https://github.com/cr2007/mcp-wordle-python/blob/main/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`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py):

```python

# 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`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py) at lines 30‑38, the `get_wordle_data` function is registered with descriptive attributes:

```python
@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:

```python
@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`](https://github.com/cr2007/mcp-wordle-python/blob/main/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`](https://github.com/cr2007/mcp-wordle-python/blob/main/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`](https://github.com/cr2007/mcp-wordle-python/blob/main/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.