Exposing Resources and Prompts, Not Just Tools, from an MCP Server

Tools are actions. Many agent workflows also need readable context and reusable templates.

MCP models those as resources (URI-addressable data) and prompts (named message templates with arguments).

Summary

Keep your tools, then declare resources for files or API snapshots agents should read, and prompts for multi-step task templates hosts can insert. List, read, and get each primitive through the SDK; document URIs and prompt args as carefully as tool schemas.

Recipe

1. Inventory what is currently stuffed into tool return strings (configs, docs, large JSON).
2. Promote stable, readable payloads to resources with clear URIs (scheme://path).
3. Identify repeated user-facing task setups and encode them as prompts with typed args.
4. Register list/read (resources) and list/get (prompts) handlers via FastMCP or the TS SDK.
5. Advertise capabilities so clients know resources/prompts exist (SDKs usually set this when you register).
6. Test: list resources → read one URI; list prompts → get one with sample args.
7. Teach host users when to attach a resource vs call a tool (read vs side effect).
8. Version URIs and prompt names; avoid silent renames that break saved workflows.

Working Example

Python FastMCP sketch

# verify decorator APIs at build for your mcp package version
from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("catalog-server")
 
DOCS = {
    "intro": "# Product intro\nWelcome to the catalog API.",
    "limits": "# Rate limits\n100 req/min per key.",
}
 
@mcp.resource("docs://{slug}")
def read_doc(slug: str) -> str:
    """Return a markdown doc by slug."""
    return DOCS.get(slug, f"Unknown doc: {slug}")
 
@mcp.prompt()
def review_change(service: str, risk: str = "medium") -> str:
    """Template for reviewing a service change."""
    return (
        f"Review the proposed change for `{service}`.\n"
        f"Risk level: {risk}.\n"
        "List regressions, rollout steps, and monitors to watch."
    )
 
@mcp.tool()
def list_doc_slugs() -> str:
    """List documentation slugs available as resources."""
    return ", ".join(sorted(DOCS))
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

TypeScript sketch

// Patterns - verify registerResource / registerPrompt names at build
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
 
const server = new McpServer({ name: "catalog-server", version: "1.0.0" });
 
server.registerTool(
  "list_doc_slugs",
  { description: "List documentation slugs", inputSchema: {} },
  async () => ({ content: [{ type: "text", text: "intro, limits" }] }),
);
 
// Resources and prompts: use the SDK helpers for your version, e.g.
// server.resource(...) / server.registerResource(...)
// server.prompt(...) / server.registerPrompt(...)
// Return URI, mimeType, and text/blob contents per schema.

Prefer checking the current SDK reference for exact resource / prompt registration helpers - names evolve slightly across releases.

Deep Dive

Tools vs resources vs prompts

Mixing them poorly creates confusion: a "read_file" tool that also mutates state, or a prompt that secretly calls APIs.

Resource design

• Use a URI scheme you own (docs://, config://, ticket://).
• Prefer idempotent reads.
• Large binaries may use blob content types; text/markdown is simplest for LLMs.
• Resource templates (parameters in the URI) scale better than listing millions of static entries.

Prompt design

• Arguments should be few and typed.
• Body should be the instructions you would paste into chat yourself.
• Do not embed secrets in prompt text.
• Prompts are not a substitute for server-side authorization.

Host behavior differs

Some hosts auto-fetch resources; others only list them until a user or agent requests a read.

Some hosts surface prompts as slash commands; others ignore them.

Document your primitives for the hosts you officially support.

Combining primitives

Pattern: prompt sets the task, resource supplies policy docs, tool performs the change.

That split keeps token use lower than stuffing everything into one mega-tool result.

Gotchas

1. Read tools that mutate - violates user mental model; split write tools.
2. Huge resource bodies - still burn context; consider summaries + spill files.
3. Unlisted URIs - if hosts only show listed resources, undocumented URIs never appear.
4. Prompt vs system prompt - MCP prompts do not replace your agent system policy.
5. Capability flags wrong - client never lists resources if initialize capabilities omit them.
6. URI encoding bugs - special characters in path segments break reads.
7. Stale caches - hosts may cache lists; send list-changed notifications when supported.

Alternatives

FAQs

Related

Related: Anatomy of an MCP Server: Handlers, Schemas, and Transport

Related: Building Your First MCP Server in TypeScript or Python

Related: Handling Large Tool Outputs: Auto-Spill to Sandbox Files

Related: MCP's Three Primitives: Tools, Resources, and Prompts

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.