MCP tools vs resources vs prompts: when to use each

1// TypeScript: defining a tool
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { z } from "zod";
4
5const server = new McpServer({ name: "demo", version: "1.0.0" });
6
7server.tool(
8  "search_issues",
9  "Search GitHub issues by keyword",
10  {
11    query: z.string().describe("Search keywords"),
12    repo: z.string().describe("Repository in owner/repo format"),
13    state: z.enum(["open", "closed", "all"]).default("open"),
14  },
15  async ({ query, repo, state }) => {
16    // Call GitHub API...
17    return {
18      content: [{ type: "text", text: `Found 12 issues matching "${query}" in ${repo}` }],
19    };
20  }
21);

1// TypeScript: defining a static resource
2server.resource(
3  "project-config",
4  "config://project",
5  { description: "Current project configuration" },
6  async (uri) => ({
7    contents: [{
8      uri: uri.href,
9      mimeType: "application/json",
10      text: JSON.stringify({ name: "my-app", version: "2.1.0", env: "production" }),
11    }],
12  })
13);
14
15// TypeScript: defining a resource template (dynamic URI)
16import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
17
18server.resource(
19  "user-profile",
20  new ResourceTemplate("users://{userId}/profile", { list: undefined }),
21  { description: "User profile by ID" },
22  async (uri, { userId }) => ({
23    contents: [{
24      uri: uri.href,
25      mimeType: "application/json",
26      text: JSON.stringify({ id: userId, name: "Jane Doe", role: "admin" }),
27    }],
28  })
29);

1// TypeScript: defining a prompt template
2server.prompt(
3  "code-review",
4  "Review code for bugs, security issues, and best practices",
5  {
6    language: z.string().describe("Programming language"),
7    focus: z.enum(["bugs", "security", "performance", "all"]).default("all"),
8  },
9  ({ language, focus }) => ({
10    messages: [
11      {
12        role: "user",
13        content: {
14          type: "text",
15          text: `Review the following ${language} code. Focus on: ${focus}.
16
17Check for:
18- Logic errors and edge cases
19- Security vulnerabilities (injection, XSS, auth issues)
20- Performance bottlenecks
21- Adherence to ${language} best practices
22
23Provide specific line-level feedback with severity ratings.`,
24        },
25      },
26    ],
27  })
28);

1// Decision matrix:
2//
3// | Question                          | Tool | Resource | Prompt |
4// |-----------------------------------|------|----------|--------|
5// | Who controls invocation?          | AI   | App      | User   |
6// | Does it perform an action?        | Yes  | No       | No     |
7// | Does it have side effects?        | Often| Never    | Never  |
8// | Does it need input schemas?       | Yes  | No*      | Yes    |
9// | Is it read-only?                  | No   | Yes      | Yes    |
10// | Does the model see it in context? | Via result | Via host | Via message |
11//
12// * Resource templates can have URI parameters

1# Python: all three capability types with FastMCP
2from mcp.server.fastmcp import FastMCP
3
4mcp = FastMCP("demo-server")
5
6# TOOL — model-controlled action
7@mcp.tool()
8async def search_issues(query: str, repo: str, state: str = "open") -> str:
9    """Search GitHub issues by keyword."""
10    return f'Found 12 issues matching "{query}" in {repo}'
11
12# RESOURCE — app-controlled data
13@mcp.resource("config://project")
14async def get_project_config() -> str:
15    """Current project configuration."""
16    return '{"name": "my-app", "version": "2.1.0"}'
17
18# PROMPT — user-controlled template
19@mcp.prompt()
20async def code_review(language: str, focus: str = "all") -> str:
21    """Review code for bugs, security, and best practices."""
22    return f"Review the following {language} code. Focus: {focus}."