[
    {
        "role": "user",
        "content": "I%27ve%20heard%20that%20mcp%20can%20be%20divided%20into%203%20things%3A%20Tools%3A%20Function%20calls%20the%20agent%20can%20trigger%20Resources%3A%20Data%20sources%20the%20agent%20can%20read%20Prompts%3A%20Structured%20templates%20for%20consistent%20interactions.%20describe%20a%20simple%20mcp%20server%20and%20how%20it%20fulfills%20each%20of%20those%20requirements."
    },
    {
        "role": "assistant",
        "content": "Here\u2019s a description of a simple MCP (Model Context Protocol) server \u2014 call it **SimpleMCPServer** \u2014 and how it fulfills the three core MCP primitives: **Tools**, **Resources**, and **Prompts**. I\u2019ll explain its components and operations, illustrating how each requirement is met.\n\n---\n\n## What is MCP & Its Primitives\n\nThe MCP is an open standard (created by Anthropic in late 2024) that defines how LLM-based clients (e.g. Claude, agents) can discover and interact with external tools, access contextual data, and use reusable prompt templates/workflows via a common protocol. It defines three core types of capabilities that a server exposes to clients:  \n\n- **Tools**: callable functions that perform actions (e.g. execute an API, write to DB, send an email). ([modelcontextprotocol.io](https://modelcontextprotocol.io/docs/learn/architecture?utm_source=openai))  \n- **Resources**: data sources exposed for reading or retrieval (no side-effects). For example: files, records, live system logs. ([gist.github.com](https://gist.github.com/rhizanthemum/5a7b57d9a4c945e44911c15a2d356007?utm_source=openai))  \n- **Prompts**: reusable templates, workflows or few-shot examples provided by the server to enforce consistency or structure in agent interactions. They may include placeholders/arguments. ([dev.to](https://dev.to/farhan_khan_41ec7ff11ac1d/mcp-server-core-concepts-18i8?utm_source=openai))  \n\nCommunication between client (agent) and server happens over standard transports (stdio, HTTP/SSE) using JSON-RPC 2.0, with methods for discovering, retrieving, and invoking tools/resources/prompts. ([modelcontextprotocol.io](https://modelcontextprotocol.io/docs/learn/architecture?utm_source=openai))  \n\n---\n\n## Architecture of SimpleMCPServer\n\nLet\u2019s assume SimpleMCPServer is implemented in a language like Python or TypeScript. It listens via HTTP (with optional Server-Sent Events) and implements the MCP data-layer protocol. Internally, it maintains:\n\n- A registry of **tools**: each described by name, description, input schema (possibly JSON schema), and behavior.  \n- A set of **resources**: both static (e.g. files on disk, database rows) and possibly dynamic (e.g. API results).  \n- A library of **prompts/templates**: reusable workflows or messaging patterns with arguments/placeholders.\n\nEndpoints that must be supported include (typical in MCP spec):\n\n- `tools/list` \u2014 returns metadata about available tools  \n- `tools/call` \u2014 invoke a tool with arguments  \n- `resources/list` \u2014 list available resources or resource templates  \n- `resources/read` \u2014 retrieve content of given resource(s)  \n- `prompts/list` \u2014 list available prompt templates  \n- `prompts/get` \u2014 retrieve prompt body, given name and maybe arguments ([medium.com](https://medium.com/data-bistrot/mcp-resources-and-prompts-know-things-and-reuse-intelligence-49eecb0e3335?utm_source=openai))  \n\n---\n\n## How SimpleMCPServer Fulfills the Requirements\n\nHere\u2019s how each of the three \u2014 Tools, Resources, Prompts \u2014 is fulfilled concretely in the server.\n\n| Primitive | What SimpleMCPServer Provides | Example Use Case |\n|---|---|---|\n| **Tools** | The server exposes one or more callable functions/actions. These are discovered via `tools/list`, invoked via `tools/call`. Tools have names, descriptions, input schemas, possibly flags about side-effects or permissions. | Suppose there\u2019s a tool named `send_email`, with schema: `{ \"to\": \"string\", \"subject\": \"string\", \"body\": \"string\" }`. The client (model) can choose to call `send_email` to send an email. Also maybe `query_weather(location)`. |\n| **Resources** | The server provides read-only data. This might include: static documentation files (e.g. project README), database contents (e.g. list of current tickets), live logs. Clients can discover via `resources/list`, read via `resources/read`. There may be resource templates (URIs with variables) for dynamic resources. | Example: a resource `file:///docs/api_spec.md` for the API spec. Or a template `logs://service/{serviceName}` where *serviceName* is substituted. The model can read the document to understand how to call tools properly. |\n| **Prompts** | The server offers prompt templates/workflows that standardize certain interactions. Clients can list prompts via `prompts/list`, and then retrieve or invoke prompt templates with arguments via `prompts/get` or similar. | Example prompt: `code_review` template that takes arguments like `{ language, filename, criteria }` and returns a structured prompt to guide the LLM\u2019s review. Another might be a workflow prompt `onboard_new_user` that guides through the steps of setting up a new user account, assigning roles, sending welcome email, etc. |\n\n---\n\n## Example Flow\n\nHere\u2019s an example scenario with SimpleMCPServer:\n\n1. **Client connects**: an LLM-based agent (or UI) discovers capabilities by calling `tools/list`, `resources/list`, `prompts/list`.\n\n2. **Client sees**:\n   - Tools: `send_email`, `lookup_user`, `generate_report`\n   - Resources: `docs://api_spec`, `db://users_table`, `logs://service/foo`\n   - Prompts: `code_review_template`, `user_onboarding_workflow`\n\n3. **User asks**: \u201cCould you generate a code review for the latest commit using our style guide?\u201d\n\n4. **Agent logic**:\n   - Retrieves the prompt via `prompts/get(\"code_review_template\")` with arguments `{ language: \"Python\", criteria: \"style, security\" }`.\n   - Reads the style guide resource via `resources/read(\"docs://style_guide.md\")`.\n   - Reads the code file via `resources/read(\"file:///repos/myrepo/latest_commit.py\")`.\n   - Constructs a prompt that includes the code, the style guide, and uses the template.\n   - Passes that to the LLM to produce a review.\n\n5. **If the agent also notices something actionable**: e.g. \u201cUser\u2019s email is not set up properly,\u201d it might call the `send_email` tool to notify the user. That happens via `tools/call`.\n\n---\n\n## Server Transport & Communication Details\n\n- The server implements **JSON-RPC 2.0**, with methods like `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`. ([modelcontextprotocol.io](https://modelcontextprotocol.io/docs/learn/architecture?utm_source=openai))  \n- Transport may be over HTTP (REST/HTTP + SSE for notifications), or via stdio pipes for local servers (such as a desktop app). ([modelcontextprotocol.io](https://modelcontextprotocol.io/docs/learn/architecture?utm_source=openai))  \n- The server may also support **notifications** for changes: e.g., `notifications/resources/list_changed` when new resource files are added; or resource content changes. ([gist.github.com](https://gist.github.com/rhizanthemum/5a7b57d9a4c945e44911c15a2d356007?utm_source=openai))  \n\n---\n\n## Permissions, Annotations, and Best Practices\n\n- Tools have annotations: whether they are destructive, read-only, have side effects, require secrets, etc. These help clients and operators understand risk. ([docs.aws.amazon.com](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp.html?utm_source=openai))  \n- Resources are usually read-only; they should not allow arbitrary execution or writing. That minimizes risk.  \n- Prompts, being templates, avoid redundancy and help maintain consistency.  \n- Schema definitions (for tools' input) help validate calls and ensure reliable usage.  \n\n---\n\n## Summary Checklist\n\nHere\u2019s a checklist that SimpleMCPServer must satisfy to properly implement Tools, Resources, and Prompts:\n\n- Tools\n  - discoverable (`tools/list`)\n  - have names, descriptions, input schema\n  - callable (`tools/call`)\n  - annotations about behavior (read-only, side-effects)\n- Resources\n  - discoverable (`resources/list`)\n  - readable (`resources/read`)\n  - support static content (files) & possibly dynamic content (via templates)\n  - read-only, no side-effects\n- Prompts\n  - discoverable (`prompts/list`)\n  - retrievable or invocable (`prompts/get`)\n  - accept arguments/placeholders\n  - reusable templates/workflows for common tasks  \n\nIf SimpleMCPServer implements those, it provides the full capabilities of MCP in terms of Tools, Resources, and Prompts.\n\n---\n\nIf you like, I can sketch some **code structure or folder layout** for such a server (e.g. in Python or NodeJS) to make it even more concrete. Do you want me to do that?"
    },
    {
        "role": "user",
        "content": "ok%2C%20so%20tools%2Fcall%20and%20prompts%2Fget%20sound%20pretty%20similar%20in%20that%20we%27re%20filling%20in%20parameters%20and%20asking%20it%20to%20do%20something.%20when%20is%20each%20more%20appropriate%3F"
    },
    {
        "role": "assistant",
        "content": "Great question \u2014 \u201ctools/call\u201d and \u201cprompts/get\u201d do indeed have overlap in that both involve parameters and result in something being done or generated. But they serve different roles in MCP, and choosing which to use depends on the goal: whether you want the model to perform an action (often with side-effects), or to produce structured text/instructions/templates. Below are distinctions and guidelines for when each is more appropriate.\n\n---\n\n## Key Differences\n\n| Aspect | tools/call | prompts/get |\n|---|---|---|\n| **Intention / Purpose** | Invoke an operation or action, often with side-effects or external impact (e.g. send an email, write to a database, call an external API). | Get a reusable template or instructions; produce text to guide an interaction. No side-effects. |\n| **Who triggers usage** | The agent (i.e. the LLM) decides: after interpreting user intent, the model chooses to call a tool. ([docs.leanmcp.com](https://docs.leanmcp.com/guides/prompts-and-resources?utm_source=openai)) | The user (or agent acting at user\u2019s behest) selects or requests a prompt. Prompts are templates/resources for \u201cwriting\u201d rather than execution. ([docs.tambo.co](https://docs.tambo.co/concepts/model-context-protocol/features?utm_source=openai)) |\n| **Side-effects** | Usually yes \u2014 state-changes, external action, resource usage. If you\u2019re using `tools/call`, it might send data, change system state, etc. | No \u2014 just a template/template output. The prompt itself doesn\u2019t do anything except generate text. |\n| **Schema / Arguments** | Tools have strong input schemas (often JSON-schema style) for validating arguments to the call. Outputs may also be structured. ([mrg.cs.ox.ac.uk](https://mrg.cs.ox.ac.uk/talks/2026/01/mrg-wenbo-zhang/A-brief-introduction-to-the-MCP-A2A-Protocols.pdf?utm_source=openai)) | Prompts may accept parameters/placeholders (arguments) so that template can be customized. But it\u2019s about generating structured content rather than executing logic. ([fastmcp.wiki](https://fastmcp.wiki/en/servers/prompts?utm_source=openai)) |\n| **Support and client capability** | Broad support: tool invocation is central to MCP and widely supported across clients. ([docs.leanmcp.com](https://docs.leanmcp.com/guides/prompts-and-resources?utm_source=openai)) | More limited: not all clients support prompt templates or full parameterization; some clients simulate prompt behavior via tools (\u201cprompts as tools\u201d) for compatibility. ([docs.tambo.co](https://docs.tambo.co/concepts/model-context-protocol/features?utm_source=openai)) |\n\n---\n\n## When to Use tools/call\n\nUse this when you want the model (or agent) to **perform a specific action** \u2014 e.g.:\n\n- Fetch data from an external system via API  \n- Update a resource (e.g. write to database, send email, trigger an event)  \n- Carry out workflows that require operational capabilities  \n\nThe agent selects the tool based on context. The tool must be well-specified (name, input schema, description) so the LLM knows *when* and *how* to call it.  \n\n**Examples**:  \n- `tools/call(\"send_email\", {to: \"...\", subject: \"...\", body: \"...\"})`  \n- `tools/call(\"add_user\", {username: \"...\", role: \"editor\"})`\n\n---\n\n## When to Use prompts/get\n\nUse this when you want a **template or structured instruction set** \u2014 for instance:\n\n- A user wants to craft a bug report, write marketing copy, or summarize code according to a style guide.  \n- You want to standardize messaging (e.g. \u201creview this code against our security checklist\u201d) across many different instances.  \n- You want to provide partial automation by helping assemble inputs for tools, rather than invoking the tool immediately.  \n\nPrompts/get are good when no external state change is needed, just content generation or guiding text.\n\n**Examples**:  \n- `prompts/get(\"code_review_template\", {language: \"Python\", focus: [\"style\", \"security\"]})` \u2192 returns a template the user or agent can fill or embed.  \n- `prompts/get(\"email_template\", {theme: \"formal\", purpose: \"welcome_new_user\"})`\n\n---\n\n## When One Might Simulate the Other\n\nBecause not all clients support prompt templates, some servers support \u201cprompts-as-tools\u201d transforms: i.e. expose prompts via tools so agents can still access the functionality via `tools/call`. ([gofastmcp.com](https://gofastmcp.com/servers/transforms/prompts-as-tools?utm_source=openai))  \n\nSimilarly, a prompt template could be used to generate instructions that then lead the model to decide which tools to call. In that sense, prompts can guide tool use, but prompts themselves are not tools.  \n\n---\n\n## Decision Guide: Which to Choose\n\nHere\u2019s a quick checklist to decide:\n\n1. **Is an external action or side-effect required?**  \n   \u2192 Yes \u2192 Use `tools/call`  \n   \u2192 No \u2192 Use `prompts/get`\n\n2. **Do you want a reusable structure/template for human or agent input?**  \n   \u2192 Yes \u2192 `prompts/get`\n\n3. **Do you want to enforce consistent wording, formatting, or sequence?**  \n   \u2192 `prompts/get` to create and reuse template  \n\n4. **Will the client(s) in your ecosystem support prompt templates?**  \n   If not, consider using \u201cprompts as tools\u201d or implement via tools.\n\n5. **Is execution logic or computation needed (e.g. \u201clist tickets\u201d, \u201ccalculate sum\u201d)?**  \n   \u2192 Use tools.\n\n---\n\n## Example Scenarios\n\n- **Scenario A**: \u201cUser says: email this document to our legal team.\u201d  \n   \u2192 The system should use `tools/call(\"send_email\", {...})`.\n\n- **Scenario B**: \u201cUser says: I need to write an internal memo about our Q1 performance using our internal style guide.\u201d  \n   \u2192 Use `prompts/get(\"internal_memo_template\", {audience: \"management\", tone: \"formal\"})`, possibly also read resource `resources/read(\"style_guide.md\")`.  \n\n- **Scenario C**: Creating a UI slash command \u201cCreate Pull Request Review\u201d that sets up initial text: this is a prompt.\n\n- **Scenario D**: Automate a workflow that both generates a draft and then sends to someone: might combine both \u2014 prompt for draft, then tool call to send.\n\n---\n\nIf you like, I can walk through actual MCP spec sections that define tools vs prompts/get, with the JSON schemas, to help ground your implementation. Do you want that?"
    }
]