Lesson 6 - Step 2 of 5

Resource Definition

Learn the required and optional fields for defining MCP resources.

Resource Object Structure

Every resource in MCP is defined by an object with specific fields. Some are required, others are optional but recommended.

json 
{
    "uri": "file:///project/config.json",      // Required
    "name": "config.json",                      // Required
    "description": "Application configuration", // Optional
    "mimeType": "application/json"              // Optional
}

Required Fields

uri (string)

The unique identifier for the resource. Must be a valid URI that the server can use to locate and retrieve the resource content.

python 
# Valid URI examples
uri = "file:///home/user/documents/report.pdf"
uri = "db://postgres/users/42"
uri = "http://api.example.com/config"
uri = "git://repo/main/src/app.py"
URI Must Be Unique

Each resource must have a unique URI within the server. The URI is how clients identify which resource they want to read.

name (string)

A human-readable name for the resource. This is what gets displayed in client UIs (like file browsers or resource pickers).

python 
# Good names are descriptive but concise
name = "config.json"           # Filename for files
name = "User #42"              # Descriptive for database records
name = "API Configuration"     # Human-friendly for abstract resources

Optional Fields

description (string)

A longer description explaining what the resource contains and why it might be useful. This helps users and AI understand the resource's purpose.

python 
# Descriptions should explain the content and purpose
description = "Main application configuration including database settings and API keys"
description = "User profile data including name, email, and preferences"
description = "README with project setup instructions and architecture overview"

mimeType (string)

The MIME type of the resource content. This helps clients know how to display or process the data.

Content Type MIME Type
Plain text text/plain
JSON application/json
Markdown text/markdown
HTML text/html
Python text/x-python
JavaScript text/javascript
Binary/Image image/png, image/jpeg

Defining Resources in Python

Here's how to define resources in your MCP server:

python 
"""
resources.py - Defining MCP resources
"""

# Define resources as a list of dictionaries
RESOURCES = [
    {
        "uri": "file:///project/config.json",
        "name": "config.json",
        "description": "Application configuration with database and API settings",
        "mimeType": "application/json"
    },
    {
        "uri": "file:///project/README.md",
        "name": "README.md",
        "description": "Project documentation and setup instructions",
        "mimeType": "text/markdown"
    },
    {
        "uri": "db://app/settings",
        "name": "Application Settings",
        "description": "Runtime settings stored in the database",
        "mimeType": "application/json"
    }
]


def get_resource_by_uri(uri: str) -> dict | None:
    """Find a resource by its URI."""
    for resource in RESOURCES:
        if resource["uri"] == uri:
            return resource
    return None


def list_resources() -> list[dict]:
    """Return all available resources."""
    return RESOURCES

Using Dataclasses for Type Safety

For better type safety, you can use Python dataclasses:

python 
"""
resources_typed.py - Type-safe resource definitions
"""

from dataclasses import dataclass, asdict
from typing import Optional


@dataclass
class Resource:
    """Represents an MCP resource."""
    uri: str
    name: str
    description: Optional[str] = None
    mimeType: Optional[str] = None

    def to_dict(self) -> dict:
        """Convert to dictionary, excluding None values."""
        return {k: v for k, v in asdict(self).items() if v is not None}


# Define resources with type checking
resources = [
    Resource(
        uri="file:///project/config.json",
        name="config.json",
        description="Application configuration",
        mimeType="application/json"
    ),
    Resource(
        uri="file:///project/README.md",
        name="README.md",
        description="Project documentation",
        mimeType="text/markdown"
    )
]


def list_resources() -> list[dict]:
    """Return all resources as dictionaries."""
    return [r.to_dict() for r in resources]
Best Practices
  • Always include mimeType when you know it — it helps clients render content correctly
  • Write clear descriptions — they help the AI understand when a resource is relevant
  • Use consistent URI schemes within your server
  • Keep names short but descriptive