Exposing Readable Data as MCP Resources

A resource is how an MCP server hands over data for a client to read, addressed by a URI rather than invoked like a function.

Files, database rows, configuration values, and API responses are all natural fits for resources once you think of them as things a client can fetch, not actions a model performs.

Summary

Resources in the Python MCP SDK are defined with the @mcp.resource() decorator, given a URI or a URI template as its argument.

A static resource has a fixed URI, like config://settings, while a templated resource uses placeholders in curly braces, like notes://{name}, that become function parameters.

Because a resource represents a read, it should never mutate state or trigger a side effect; that distinction is what separates a resource from a tool.

Returning a sensible MIME type alongside the content helps the client decide how to render or parse what it gets back, whether that is plain text, JSON, or an image.

Resources pair naturally with tools: a tool can create or update something, and a resource can expose the result for later reading.

Recipe

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("resource-recipes")
 
@mcp.resource("config://settings")
def get_settings() -> str:
    """Return the current server configuration as JSON."""
    return '{"theme": "dark", "max_results": 20}'
 
@mcp.resource("notes://{name}")
def get_note(name: str) -> str:
    """Return the contents of a named note."""
    return f"Contents of note '{name}'"

When to reach for this:

• The data is meant to be read, not acted on, such as a file, a config value, or a database row.
• You want the client to be able to list and fetch the data without the model having to construct a tool call.
• The same piece of data might be attached as context directly by the application, not only fetched on the model's request.
• You want a stable, addressable identifier (a URI) for a specific piece of data that can be referenced consistently.

Working Example

# server.py
import json
import sqlite3
from pathlib import Path
 
from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("docs-resources")
 
DB_PATH = Path(__file__).parent / "articles.db"
DOCS_DIR = Path(__file__).parent / "docs"
 
 
def _get_db() -> sqlite3.Connection:
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    return conn
 
 
@mcp.resource("articles://{article_id}")
def get_article(article_id: str) -> str:
    """Return a single article row as JSON, addressed by its id."""
    conn = _get_db()
    try:
        row = conn.execute(
            "SELECT id, title, body FROM articles WHERE id = ?", (article_id,)
        ).fetchone()
        if row is None:
            raise ValueError(f"No article found with id {article_id}")
        return json.dumps(dict(row))
    finally:
        conn.close()
 
 
@mcp.resource("docs://{filename}")
def get_doc_file(filename: str) -> str:
    """Return the raw text of a markdown file from the docs directory."""
    path = (DOCS_DIR / filename).resolve()
    if DOCS_DIR.resolve() not in path.parents:
        raise ValueError("filename must stay within the docs directory")
    if not path.exists():
        raise FileNotFoundError(f"No such file: {filename}")
    return path.read_text(encoding="utf-8")
 
 
@mcp.resource("stats://article-count")
def get_article_count() -> str:
    """Return the total number of articles as a static summary resource."""
    conn = _get_db()
    try:
        count = conn.execute("SELECT COUNT(*) FROM articles").fetchone()[0]
        return json.dumps({"article_count": count})
    finally:
        conn.close()
 
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

What this demonstrates:

• A templated resource (articles://{article_id}) reading a single row from a real database connection.
• A templated resource (docs://{filename}) serving files from disk, with a path traversal guard before touching the filesystem.
• A static resource (stats://article-count) with no parameters, useful for summary or aggregate data.
• Consistent use of json.dumps so structured data comes back in a predictable, parseable shape.
• Raising exceptions for a missing row or missing file, exactly like a tool would, since resources can still fail.

Deep Dive

How It Works

• @mcp.resource("scheme://path/{param}") registers a URI template; the SDK extracts {param} segments and passes them as function arguments when a matching URI is read.
• A client discovers resources with list_resources() (for concrete URIs) or list_resource_templates() (for templated ones), then reads a specific URI with read_resource(uri).
• Unlike a tool call, a resource read has no separate "arguments" object; every parameter comes from the URI itself, which keeps resources addressable and cacheable.
• The scheme portion of the URI (config://, notes://, docs://) is arbitrary and chosen by you; it is not a real network protocol, just a namespace.
• The SDK infers a MIME type from the return value where it can, but you can be explicit for anything other than plain text.

Choosing a URI Scheme

Python Notes

# Guard against path traversal whenever a resource reads from disk using a
# user-supplied path segment.
path = (DOCS_DIR / filename).resolve()
if DOCS_DIR.resolve() not in path.parents:
    raise ValueError("filename must stay within the docs directory")

Parameters & Return Values

Gotchas

• Treating a resource as an action. A resource named send_email://{to} implies a side effect and misleads clients that assume resources are safe to read repeatedly. Fix: move anything with a side effect into a tool.
• No path traversal guard on filesystem-backed resources. A URI like docs://../../etc/passwd can escape the intended directory if you build a path naively. Fix: resolve the path and confirm it stays inside the allowed root before reading.
• Returning unstructured text for what is really structured data. Callers then have to parse ad hoc formats instead of JSON. Fix: return json.dumps(...) for anything with more than one field.
• Opening a database connection per resource without closing it. Under load this leaks connections and eventually exhausts the pool. Fix: use a try/finally (as shown above) or a connection context manager.
• Overloading one resource template to also accept optional query-style parameters. URI templates in MCP are path-based, not query-string based, so this gets awkward and inconsistent. Fix: use separate resources or a tool if the data-selection logic gets complex enough to need optional filters.
• Silently returning an empty string when a lookup misses. A caller cannot tell "no data" from "an error occurred." Fix: raise an exception with a clear message when the requested resource genuinely does not exist.

Alternatives

FAQs

Related

• Understanding MCP: Tools, Resources, and Prompts - the conceptual distinction between resources, tools, and prompts.
• MCP Core Concepts Basics - a minimal stdio server and client to build resources on top of.
• Defining Callable Tools in an MCP Server - the sibling primitive for actions and computations.
• MCP Tools vs Resources vs Prompts Comparison - deciding which primitive fits a given capability.
• MCP Core Concepts Best Practices - a checklist for resource URI design.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the current Model Context Protocol specification. Model names, SDK versions, and the MCP spec move quickly - verify current specifics at platform.claude.com/docs and modelcontextprotocol.io before relying on them.