Clients, Servers, Tools, Resources, And Prompts
MCP tools, resources and prompts differ by who controls them, not by what they read. Here is the one question that sorts any capability into the right bucket.
The five pieces
Every MCP integration is built from the same small set of roles. Getting this model right before you code is what stops you from building a server that dumps too much context or exposes actions it should not.
- Client: the application the user runs, such as Claude Desktop, Claude Code, or Cursor. The client hosts the agent and connects out to your server over a transport, either stdio (the client launches your server as a subprocess) or Streamable HTTP (the client talks to a single HTTP endpoint on a remote server).
- Server: the process you write. It advertises what it offers during an initialize handshake and answers the client's JSON-RPC 2.0 requests over the protocol.
- Tools: actions the agent can call, such as create_ticket or lookup_customer. Each has a name, a description, and a JSON Schema for its inputs. These are the parts that do something, and they carry the most risk.
- Resources: read-only context the agent can pull in, addressed by URI, such as a document, a record, or a config file. Resources give grounding without granting write access.
- Prompts: reusable templates the client can invoke for common tasks, so a proven workflow is a menu item rather than something the agent improvises each time.
See it in real protocol traffic
The whole protocol is readable JSON-RPC. When a client connects and asks what tools exist, the exchange looks like this:
// client -> server
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
// server -> client
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [{
"name": "lookup_customer",
"description": "Look up a customer record by account ID. Read-only.",
"inputSchema": {
"type": "object",
"properties": {
"account_id": { "type": "string", "description": "e.g. acct_4412" }
},
"required": ["account_id"]
}
}]
}
}
When the agent decides to use the tool, the client sends tools/call with arguments, and your server returns content blocks. Resources use resources/list and resources/read with a URI, and prompts use prompts/list and prompts/get. Five method families cover almost everything you will build.
One server, all three primitives
Here is a compact FastMCP server that exposes one of each, so you can see how differently they are declared:
from fastmcp import FastMCP
mcp = FastMCP("support-desk")
@mcp.tool
def create_ticket(subject: str, body: str, priority: str = "normal") -> str:
"""Create a support ticket. Use for new customer issues only."""
ticket = helpdesk.create(subject=subject, body=body, priority=priority)
return f"Created ticket {ticket.id}"
@mcp.resource("docs://refund-policy")
def refund_policy() -> str:
"""The current refund policy document. Read this before discussing refunds."""
return open("/srv/policies/refunds.md").read()
@mcp.prompt
def triage_ticket(ticket_id: str) -> str:
"""Standard triage workflow for an incoming ticket."""
return (
f"Read ticket {ticket_id}, classify severity using the refund-policy "
"resource if money is involved, then draft a first response. "
"Do not create new tickets during triage."
)
if __name__ == "__main__":
mcp.run()
Which bucket does a capability belong in?
| Question | Tool | Resource | Prompt |
|---|---|---|---|
| Does it change anything? | Can, so gate it | Never | Never directly |
| Who initiates it? | The model, mid-task | Model or user, for context | The user, from a menu |
| Typical example | create_ticket, update_status | Policy doc, schema, record | Weekly report workflow |
| Main risk | Unwanted actions | Oversized or sensitive payloads | Stale or overloaded templates |
How a session flows
- The client starts your server (stdio) or connects to its endpoint (Streamable HTTP) and performs the initialize handshake, exchanging protocol versions and capabilities.
- The client calls tools/list, resources/list, and prompts/list, and your server responds with schemas and descriptions.
- During a task, the agent decides which tool to call or which resource to read, and the client sends that request to your server.
- Your server does the work, usually by calling an API underneath, and returns a result the agent folds into its context for the next step.
Why the split matters
The separation between tools, resources, and prompts is a safety design, not just naming. Tools act, so they are where you enforce permissions and approvals. Resources only read, so they are safer to expose broadly, but their size still matters because everything a resource returns lands in the agent's context. Prompts capture the workflows you want repeated correctly. Keeping each in its lane means you can reason about risk one category at a time, and it is the first thing a buyer will look at when deciding whether to trust your server.
Capabilities and versions, briefly
Two protocol details are worth knowing even at this stage. First, the initialize handshake negotiates capabilities: a server declares which primitives it supports (tools, resources, prompts, and optional extras like resource subscriptions), and a client declares what it can handle, so neither side calls methods the other does not implement. Second, the protocol itself is versioned by revision date, and client and server agree on a revision during the handshake. You rarely touch either detail directly because the SDKs negotiate for you, but when a client mysteriously ignores your prompts or resources, the first thing to check in the Inspector is what capabilities the handshake actually advertised. A surprising number of "the client is broken" reports are a server that never registered the primitive it thinks it exposes, and the handshake shows that in one glance.
The single question that sorts every capability
The table gives you four questions. In day-to-day design you only need one, and it is about control rather than about data: who decides when this runs?
- If the model should decide, mid-task, without anyone being asked - it is a tool.
- If the host application should decide, to put grounding in front of the model before or during a task - it is a resource.
- If a person should decide, by picking it deliberately from a menu - it is a prompt.
Run that question over three capabilities and watch how fast it settles arguments.
"The agent needs the customer's current plan and billing status." The model should be able to fetch this whenever a conversation turns to billing, without a human choosing to attach it. That is model-controlled, so it is a tool - get_account(account_id) - even though it only reads. Read-only does not automatically mean resource; the deciding factor is who initiates it.
"Every answer about refunds must follow the current refund policy." Nobody wants the model to decide whether to consult the policy. The host should attach it whenever refunds are in scope. Application-controlled, so a resource at a stable URI.
"Support leads run a Monday account review the same way every week." A human starts this, on purpose, and the value is that it runs identically each time. User-controlled, so a prompt.
Notice that "read-only" appears in all three and settles nothing. The control model settles all three in one pass.
Resources in practice: URIs, templates, and size discipline
A static resource like docs://refund-policy is the easy case. Real servers usually need a family of them, which is what URI templates are for:
from fastmcp import FastMCP
mcp = FastMCP("support-desk")
@mcp.resource("account://{account_id}/summary")
def account_summary(account_id: str) -> str:
"""One-screen summary of an account: plan, status, open tickets."""
a = billing.get(account_id)
open_tickets = helpdesk.count_open(account_id)
# Deliberately a summary, not a dump. Everything returned here lands in
# the agent's context window and is paid for on every subsequent turn.
return (
f"Account {account_id}\n"
f"Plan: {a.plan} ({a.seats} seats)\n"
f"Status: {a.status}, renews {a.renews_on}\n"
f"Open tickets: {open_tickets}"
)
The comment in that handler is the whole lesson. The most common resource bug is not a crash, it is a handler that returns a full record - forty fields, nested JSON, timestamps nobody will read - because that was the shape the API already returned. The agent then carries all of it for the rest of the session. Two habits prevent it: return prose or a trimmed structure rather than raw API output, and put a hard cap on length in the handler so a pathological record cannot blow the window.
The same discipline applies to what you name things. A resource URI is a public contract - once a client's saved workflow references account://{id}/summary, renaming it breaks them silently. Pick a scheme per domain, keep the path shallow, and treat renames as breaking changes.
Prompts are where institutional knowledge goes
Prompts are the primitive people skip, and the reason is that they look redundant - the user could just type the instructions. That is true and it misses the point. A prompt is the place a company's way of doing something stops living in one experienced person's head.
The triage prompt earlier encodes four decisions: read the ticket first, use the policy resource when money is involved, draft rather than send, and do not create tickets during triage. Those four lines are what a good support lead knows and a new hire does not. Written as a prompt, every person on the desk runs the same triage on their first day, and when the policy changes you edit one file rather than retraining eight people.
Prompts also take arguments, which is what makes them reusable rather than a snippet:
@mcp.prompt
def weekly_account_review(account_id: str, weeks: int = 1) -> str:
"""Monday account review. Read-only: never changes anything."""
return (
f"Review account {account_id} over the last {weeks} week(s).\n"
f"1. Read account://{account_id}/summary.\n"
"2. List open tickets by age, oldest first.\n"
"3. Flag anything untouched for more than 3 business days.\n"
"4. Output: three bullets of status, then one recommended action.\n"
"Do not create, update, or close anything. This is a read-only review."
)
Note the last line. A prompt cannot enforce anything - it is text the model receives, not a permission - so the enforcement still has to live in the tools. But stating the intent in the prompt and enforcing it in the tool layer is belt and braces, and it makes the server's behaviour legible to whoever reviews it before signing off.
Host, client, server - the distinction that matters when things break
The five roles above simplify one thing worth un-simplifying now, because the debugging vocabulary depends on it. What you install is a host application - Claude Desktop, Claude Code, Cursor. Inside it, the host maintains one client connection per server it talks to. So a host running four MCP servers holds four clients, each with its own handshake, its own capability set, and its own lifecycle.
That structure explains behaviour that otherwise looks random. Restarting one misbehaving server does not disturb the other three. A capability your server declared is negotiated with that one client only. And when two servers both expose a tool called search, the host has to disambiguate them, which is why generic tool names cause trouble the moment a user installs a second server. A tool name is not scoped to you as strongly as you would like, so helpdesk_search_tickets ages far better than search.
A naming convention that pays for itself
Three rules, applied from the first tool you write:
- Prefix by domain, not by company.
helpdesk_create_ticket, notacme_create. The model is selecting on meaning, and the domain is the meaningful part. - Verb first, and let the verb carry the risk.
get_,list_, andsearch_read;create_,update_, anddelete_write. A reviewer should be able to sort your tools/list output into safe and dangerous without opening the code. - One noun per tool. If the name needs "and" in it, it is two tools. Narrow tools are selected more reliably and are far easier to gate individually.
None of this is protocol-mandated. It is the convention that survives contact with a client whose security reviewer wants a one-page list of everything an agent can do to their systems - and producing that page in thirty seconds is a large part of why a server gets approved.
What the protocol looks like as of August 2026
MCP revisions are dated, and the current one is 2026-07-28. If you learned MCP from material written in 2025, five things have moved, and two of them will change code you write. Everything in this section is from the specification's own architecture documentation at that revision - check the date on anything you read elsewhere, because this is a fast-moving protocol and stale tutorials are the norm.
- The protocol is stateless. Every request carries what the server needs to process it on its own: the protocol version and the client's capabilities travel in a
_metafield on each request, and clients normally identify themselves there too. Servers are not meant to infer anything from previous requests. - Discovery is a request, not a handshake step. Servers must implement
server/discover, which returns supported versions, capabilities, and server identity. Calling it is optional - because every request already carries the version and capabilities, a client can just send the request it wants and handle a version error if one comes back. Discovery is a convenience that fetches all three in one round trip, and its response is cacheable, with the server returning attlMsfreshness hint and acacheScope. - Elicitation is now the client primitive that matters. Servers can ask the user for more information or for confirmation of an action via
elicitation/create. This is the sanctioned way for a server to say "I need one more field before I do this" rather than guessing. - Sampling and logging are deprecated at this revision.
sampling/createMessage- the mechanism that let a server borrow the client's model - is deprecated, and new implementations are directed to integrate with a model provider's API directly. Server-side logging over the protocol is likewise deprecated in favour of writing to stderr on stdio, or using OpenTelemetry. - Change notifications are opt-in. Rather than the server pushing whatever it likes, the client opens a long-lived
subscriptions/listenstream naming the notification types it wants; the server acknowledges the subset it will honour and delivers matching notifications on that stream. Delivery is explicitly best-effort, particularly across transport reconnects, so a client should still poll to keep results fresh.
The primitive model itself is unchanged, which is why the sorting question in this lesson keeps its value: servers expose tools, resources, and prompts; each has */list for discovery, retrieval methods, and in the case of tools tools/call for execution. There are still exactly two transports - stdio for local processes, and Streamable HTTP (HTTP POST with optional Server-Sent Events for streaming) for remote servers, where the specification recommends OAuth for obtaining tokens.
One newer piece worth knowing before you promise a client anything about long jobs: the protocol supports optional extensions on top of the core, and the Tasks extension lets a server return a durable handle for a long-running request so the client can poll for status and collect the result later. If you have been designing around "my tool takes four minutes and the client times out", that is the shape to look at rather than inventing your own polling tool.
The practical consequence of statelessness deserves emphasis, because it is where servers written against older mental models break. Do not stash per-connection state in your server and assume the next call belongs to the same conversation. If a tool needs to know something the last call established, that fact belongs in the tool's arguments, in a resource the client can read, or in your own backend keyed by something the caller passes - not in a module-level variable that happens to survive between requests on a local stdio process and then falls apart the moment you host the same code.
Worked artefact: the one-page capability sheet
The commercial payoff of the naming rules is a document you can produce on demand. This is the artefact a buyer's security reviewer asks for, and having it written before they ask is frequently the difference between a two-week approval and a two-month one. Here it is filled in for the support-desk server:
SERVER: support-desk VERSION 1.4 TRANSPORT: Streamable HTTP
IDENTITY: per-user OAuth; every call logged with the acting user
TOOLS THAT ONLY READ
helpdesk_list_tickets(account_id, status?) -> up to 50 tickets, IDs+subjects
helpdesk_get_ticket(ticket_id) -> one ticket, body truncated 4k
billing_get_account(account_id) -> plan, status, renewal date
TOOLS THAT CHANGE SOMETHING
helpdesk_create_ticket(subject, body, priority)
Writes: creates a ticket. Cannot set assignee or close.
helpdesk_update_ticket_status(ticket_id, status)
Writes: status only, and only within {open, pending, resolved}.
Cannot delete. Cannot reopen a ticket closed more than 30 days.
NOTHING ELSE WRITES. There is no delete tool and no billing write tool.
RESOURCES (read-only, no arguments beyond the URI)
docs://refund-policy static, ~2 KB
account://{account_id}/summary trimmed summary, capped at 1 KB
PROMPTS (user-invoked only)
triage_ticket(ticket_id)
weekly_account_review(account_id, weeks=1)
DATA THAT NEVER LEAVES
Card numbers, bank details, and full addresses are stripped in the
handler before any response is returned. Verified by test suite.
Notice what makes it convincing: the read/write split falls straight out of the verb-first naming, every write tool states its limits rather than its features, and the "nothing else writes" line is a claim a reviewer can check against your tools/list output in one glance. That last property is the whole reason for the convention.
Troubleshooting the three primitives
| Symptom | Likely cause | How to confirm and fix |
|---|---|---|
| Your resources never appear in the client | Either the server did not register the primitive, or the host does not surface resources in its UI | Call resources/list in the Inspector. If it returns your entries, the server is fine and the gap is the host's interface |
| The agent reads a resource once and then works from memory of it | Expected. Resource content is context, not a live feed | If freshness matters within a session, make it a tool the model can call again, not a resource |
| Context fills up quickly in long sessions | A resource or a tool is returning raw API output | Print the byte length of every handler's return value in a test. Cap the worst offender in the handler, not in the prompt |
| The model picks the wrong tool between two similar ones | The descriptions overlap because both say what the tool does, not when to use it | Rewrite both descriptions so each names its trigger and explicitly rules out the other's case |
| A tool works alone and fails when a second server is installed | Tool-name collision - the host holds one client per server and must disambiguate | Rename with a domain prefix. This is a breaking change for existing users, so do it before you have any |
| A tool that takes minutes times out in the client | You are holding a request open for work the protocol expects to be quick | Look at the Tasks extension, which returns a durable handle to poll, instead of building your own status tool |
| Works locally on stdio, misbehaves once hosted | Hidden per-connection state, now that many clients share the server | Remove module-level mutable state; the protocol is stateless by design and your server should be too |
Common mistakes
- Turning everything into a tool, including things that should be read-only resources, which hands the agent write access it never needed.
- Exposing a resource that returns an entire production dataset, so the agent pulls far more context than the task requires.
- Skipping prompts, then wondering why the agent runs a critical workflow slightly differently every time.
What you should be able to do now
- Draw an MCP integration on one page: client, server, and three labelled buckets.
- Read a tools/list response and explain every field in it.
- Declare a tool, a resource, and a prompt in FastMCP and say why each is in its bucket.
- Given a new capability, place it in the right bucket using the table above and defend the choice.
Where this goes next
That is the end of the free half of this course. Between this lesson and MCP vs plain function calling you now have the two things that decide whether an MCP project succeeds before any code is written: whether the protocol removes a real constraint for you, and which bucket each capability belongs in.
The paid lessons take it from model to product. You build a first server twice - once with the TypeScript SDK, once with FastMCP - and debug both under the MCP Inspector, which is where schema mistakes surface in seconds instead of in a confused agent transcript. From there the course covers designing narrow tools, writing descriptions the model selects correctly, returning errors an agent can recover from rather than protocol faults, read-only resources at safe sizes, auth and tenant isolation once the server is hosted rather than local, and finally the commercial side: packaging, documenting, and pricing a server that other companies connect to their own systems. Each lesson ships the runnable code and the repo.
Not everyone wants to run that build. If you would rather have the boundary built and handed over, that is a project we take on - see AI automation services, or book the free automation audit and we will tell you plainly whether an MCP server is the right shape for your systems or whether a simpler integration does the job. The function calling and MCP glossary entries are the short versions if you need to brief someone else first.
Enter your email below and the free lessons plus every code sample in them - the FastMCP server, the TypeScript server, the client config blocks - arrive in one message. That part costs nothing.
Key takeaways
What to remember from this lesson
- One question sorts every capability: who decides when this runs? Model-controlled is a tool, application-controlled is a resource, user-controlled is a prompt.
- 'Read-only' settles nothing. A read-only account lookup the model triggers mid-task is still a tool; the control model decides the bucket, not the side effects.
- Everything a resource returns lands in the context window and is paid for on every later turn. Return a trimmed summary with a hard length cap, never raw API output.
- Resource URIs are a public contract. Once a saved workflow references one, renaming it breaks that client silently - treat renames as breaking changes.
- Tool names are barely scoped. Prefix by domain, put the verb first so a reviewer can sort read from write, and use one noun per tool - if the name needs 'and', it is two tools.
Try it yourself
Sort capabilities into tools, resources and prompts
One question sorts every capability: who decides when this runs? Below is a fixture list of capabilities from a dental practice server, each with a controlledBy field. Write the classifier. The check feeds it two extra cases designed to catch the classic mistake of sorting on side effects instead of control.
Try it yourself
Write the capability negotiation handshake
When a client connects, the two sides agree on a protocol version and an intersection of capabilities before a single tool runs. It is a pure function of two objects, which makes it something you can test properly. Write it. The check covers the version mismatch case, which is where real handshakes fail.
Check yourself
The three lines people blur
You expose the full text of every support ticket as a resource. What is the cost you will not see in the demo?
A saved client workflow references the resource URI crm://tickets/open. You rename it to crm://support/tickets/open. What happens?
Which name is right for a tool that reads a customer record?
Answer every question to mark.
Exercise
Bucket ten capabilities and name them so a security reviewer can skim them
- 1List ten capabilities an agent would need against a system you know. Include at least three that only read.
- 2For each one, write the answer to the single sorting question - model, application, or person decides when it runs - and then the bucket that follows: tool, resource, or prompt.
- 3Check your read-only capabilities specifically. Any that the model should be able to fetch mid-task belong in tools, not resources. Move them and note why.
- 4Name every tool using the three rules: domain prefix, verb first, one noun. Then sort your tool list into read and write columns using only the verbs.
- 5For one resource, write the FastMCP handler with a URI template, and make it return a trimmed summary with an explicit length cap rather than the full record.
- 6For one prompt, write it with at least one argument and encode four decisions a new hire would not know - including an explicit statement of what it must not change.
You are done when Every one of the ten has a bucket justified by who initiates it, your tool names sort cleanly into read and write columns from the verb alone, and your resource handler caps its own output length instead of returning whatever the API gave it.
Companion files
The support-desk server with all three primitives
A runnable FastMCP server declaring a tool, a resource, and a prompt, plus a captured tools/list response and the policy file the resource reads - so you can compare your buckets against a working one.
The free-preview pack includes 5 files of runnable code and config for Clients, Servers, Tools, Resources, And Prompts, plus the other free lessons of this course. No email needed.
Free preview pack - 10 KB zipCheck yourself
Answer before you reveal
Your prompt says 'this is a read-only review, do not change anything'. Does that stop the agent writing?Show answer
No. A prompt is text the model receives, not a permission. Enforcement lives in the tool layer. Stating the intent in the prompt and enforcing it in the tools is belt and braces, and it makes the server legible to a reviewer.
A client silently ignores your prompts. What do you check first, and where?Show answer
The capabilities advertised during the initialize handshake, visible in the MCP Inspector. A large share of 'the client is broken' reports are a server that never registered the primitive it thinks it exposes.
Why does naming a tool `search` cause trouble the moment a user installs a second server?Show answer
The host holds one client connection per server, and now two servers advertise the same tool name, so it has to disambiguate them. `helpdesk_search_tickets` ages far better.
