Using Resources

What are Resources?

Resources are data that can be loaded into the LLM’s context by the client application.

Unlike tools, which the LLM decides to call, resources are application-controlled - the client decides what to load.

Tools vs Resources

Understanding when to use each is key to effective MCP server design:

Use Tools when:

Example: search_movies_by_genre(genre: str) - The LLM decides when to search

Use Resources when:

Example: movie://123 - The client directly requests a specific movie

Creating Resources with FastMCP

FastMCP provides the @mcp.resource() decorator to expose resources. Here’s a static resource that provides reference data:

The resource starts with a URI and function signature:

@mcp.resource("catalog://genres")
async def get_genres(ctx: Context) -> dict:
    """Get all available movie genres with their counts."""

The catalog://genres URI is static - it doesn’t need any parameters because it always returns the complete list of genres. The catalog:// prefix tells clients this is a reference list they can use to look up valid genres. The function is marked as async since it makes database calls.

The code then accesses the Neo4j driver from the context:

    context = ctx.request_context.lifespan_context
    records, _, _ = await context.driver.execute_query(
        """
        MATCH (g:Genre)
        RETURN g.name AS name,
               count((g)<-[:IN_GENRE]-()) AS movieCount
        ORDER BY g.name
        """,
        database_=context.database
    )

The Cypher query finds all Genre nodes and counts how many movies belong to each genre. The alphabetical ordering makes the list easy to scan. Each result includes the genre name and its movie count.

The results are formatted in a clean, structured way:

    return {
        "genres": [
            dict(r) for r in records
        ]
    }

The returned dictionary contains a "genres" list, with each entry containing a name and movie count. This structure makes it easy for client applications to process the data programmatically.

This resource is perfect for providing reference data that clients can load upfront to understand what genres are available.

Dynamic Resource URIs

While static resources are great for reference data, sometimes you need to access specific entities. This is where dynamic URIs come in, using parameters in curly braces:

The resource definition starts with a dynamic URI pattern:

@mcp.resource("movie://{id}")
async def get_movie(id: str, ctx: Context) -> dict:
    """Get details about a specific movie by ID."""

The URI pattern movie://{id} introduces a dynamic element. When a client requests movie://603, FastMCP extracts "603" and passes it to your function’s id parameter. The type hint ensures the value is in the correct format.

The function queries the database for the movie and its genres:

    context = ctx.request_context.lifespan_context
    records, _, _ = await context.driver.execute_query(
        """
        MATCH (m:Movie {tmdbId: $id})
        RETURN m.title AS title,
               m.tagline AS tagline,
               m.released AS released,
               m.plot AS plot,
               [ (m)-[:IN_GENRE]->(g:Genre) | g.name ] AS genres
        """,
        id=id,
        database_=context.database
    )

The final step handles error checking:

    if not records:
        return {"error": f"Movie {id} not found"}

    return records[0].data()

The function returns a structured error message if no movie exists. Otherwise, it returns the movie’s details in a dictionary format following standard JSON API practices.

The dynamic pattern allows clients to:

When to Use Resources

Ideal use cases:

Not ideal for: