What you will be able to do
- Match each MCP primitive (tools, resources, prompts) to who controls it and what it is for
- Read and shape the JSON-RPC messages a server answers for tools/list, tools/call, resources/read and prompts/get
- Apply the server-side validation rules the protocol requires for tool names, resource URIs and prompt arguments
- Decide how a server authenticates its callers: environment credentials for stdio, bearer tokens in the Authorization header for HTTP
Key concept
MCP primitive control model — An MCP server offers three kinds of capability, and each one is triggered by a different party. The model calls tools, the client application attaches resources, and the user picks prompts.
1.Three primitives, three different controllers
An MCP server is a program that gives a Claude application access to an outside system, such as an issue tracker, a database or a design tool, through a standard protocol. With a Jira server and a GitHub server connected, Claude Code can take a request like "implement ENG-4521 and open a PR" from start to finish. Whatever the server wraps, it offers the client its capabilities through just three primitives. When you design a server, the first thing to decide is which primitive each capability belongs to.
| Primitive | Controlled by | What it is | Typical example |
|---|---|---|---|
| Tools | Model | Functions exposed to the LLM to take actions | API POST requests, file writing |
| Resources | Application | Contextual data attached and managed by the client | File contents, git history |
| Prompts | User | Interactive templates invoked by user choice | Slash commands, menu options |
A server announces which primitives it supports by declaring capabilities such as tools, resources or prompts. Each capability can set listChanged: true, which tells the client the server will send a notifications/.../list_changed message whenever its catalogue changes. In Claude Code, the fastest way to scaffold a server is the official plugin: run /plugin install mcp-server-dev@claude-plugins-official, then the /mcp-server-dev:build-mcp-server skill. Whether a capability should be an MCP server at all, rather than a skill or a hook, is a separate question, covered under capability mechanism selection.
Every primitive is only as safe as the authentication in front of it. A tool that writes to a database or a resource that reads a private file is reachable by whoever can open a connection, so the server's authentication decides who may use all three primitives, and the right mechanism follows from the transport.
A server that the client launches as a local subprocess over stdio does not run an authorization flow. The specification tells it to retrieve credentials from the environment instead, which is why a stdio entry carries its secret as a variable, as in --env AIRTABLE_API_KEY=YOUR_KEY. A server reachable over HTTP is a network service and should authenticate every connection. The client proves itself with an Authorization: Bearer <access-token> header, and the token must never travel in the URI query string. The OAuth flow that issues those tokens is covered under authorizing HTTP servers.
Two credentials are easy to confuse when you write a server. One is what the caller presents to your server, the bearer token. The other is what your server holds to reach the system it wraps, such as a database password. Keep them separate: a gateway that fronts other services should call each one with its own credential and never forward the caller's token.
Checkpoint 1 of 5· Match them up
Your MCP server wraps a code-hosting system. Match each primitive to the scenario that shows who triggers it.
Tap a term, then the definition that fits it.
Each primitive has its own controller. The model calls tools to take actions. The application attaches resources as context. The user picks prompts, for example as slash commands or menu options.
“Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing”Source: modelcontextprotocol.io
2.Tools: listed, called, and answered with typed results
A tool is defined by a name, a description and an inputSchema. The client discovers tools with tools/list and runs one with tools/call, passing arguments that must match the schema. Names have rules: 1 to 128 characters, case-sensitive, unique within the server, and limited to ASCII letters, digits, _, - and .. A tool that takes no parameters should still have a schema. The recommended one is { "type": "object", "additionalProperties": false }, which accepts only an empty object. Writing descriptions that a model can select tools from is a design skill of its own, covered under tool design and response shaping.
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"location": "New York"
}
}
}A tool result holds a content array, plus an isError flag that marks a failure the model should see and react to. Content blocks can be text, image, audio, a resource_link, or an embedded resource. A tool can also declare an outputSchema, and that declaration is binding. Once declared, the server must return a matching structuredContent object, and the client should validate it. The usual pattern sends both: the JSON as text in content for the model, and the same data in structuredContent for code.
Tools that create state, such as create_basket returning bsk_a1b2c3, hand the model an ID that it passes to later calls. On an authenticated server, that handle does not grant access by itself. The server checks the caller's authorization against the handle on every call. A call with an expired handle should return a tool execution error that says the handle has expired, so the model knows to create a new one.
Checkpoint 2 of 5· Check yourself
On an authenticated MCP server, one user's create_basket call returned bsk_a1b2c3. A different user's session then calls add_item with that basket_id, and the basket has not expired. What should the server do?
On an authenticated server, a handle names the state but does not grant access to it. The server checks the caller's rights against the handle on every call. The expired-handle error is only for handles that really have expired or are unknown.
“For authenticated servers, a handle is a name, not a capability. The server should validate the caller’s authorization against the handle on every call.”Source: modelcontextprotocol.io
Checkpoint 3 of 5· Check yourself
A get_weather_data tool declares an outputSchema. What does that declaration commit the server and client to?
A declared outputSchema is binding. The server must return structuredContent that matches it, and the client should validate it. The usual pattern also puts the same JSON as text in content for the model.
“Servers MUST provide structured results that conform to this schema.”Source: modelcontextprotocol.io
Sources6
3.Resources: context the client reads by URI
A resource is data that the application, not the model, pulls into context. Each resource is identified by a uri such as file:///project/src/main.rs and has a name and an optional mimeType. The client lists resources with resources/list and fetches one with resources/read, which returns either text or a base64 blob. If a server has a whole family of resources, it can publish a URI template such as file:///{path} through resources/templates/list instead of listing every file. Clients typically show resources in a tree or list so the user can pick, search and filter them.
Annotations help a client decide what to include. audience takes user, assistant or both. priority runs from 0.0 (entirely optional) to 1.0 (effectively required). lastModified lets a client sort by recency. Servers that set subscribe: true can send notifications/resources/updated when a specific resource changes.
A resource server can be attacked through the URIs it is asked to read. The protocol requires servers to validate every resource URI, and to sanitize file:// paths so that a request like file:///../../etc/passwd cannot climb out of the project directory. Sensitive resources should also be protected by access controls. An unknown URI gets a JSON-RPC error, -32602 with the message "Resource not found".
Checkpoint 4 of 5· Check yourself
A file-serving MCP server receives resources/read with the URI file:///../../etc/passwd from a client whose project lives in /project. What does the protocol require the server to do?
Servers must validate every resource URI and sanitize file:// paths against directory traversal. Neither the application-controlled trigger nor the encoding or annotations make an unsafe path safe.
“Servers MUST sanitize file paths to prevent directory traversal attacks when serving file:// resources”Source: modelcontextprotocol.io
Sources7
4.Prompts: user-chosen templates that return messages
A prompt is a named template that the user picks, typically as a slash command. prompts/list returns each prompt's name, description and arguments (each argument can be marked required). prompts/get fills the template with the user's arguments and returns ready-made messages, each with a role of user or assistant and content that can be text, image, audio or an embedded resource.
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"resultType": "complete",
"description": "Code review prompt",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Please review this Python code:\ndef hello():\n print('world')"
}
}
]
}
}Servers should validate prompt arguments before they build anything. A misspelled prompt name and a missing required argument both get -32602 (Invalid params). A failure inside the server gets -32603 (Internal error). This difference matters to the client: -32602 means the caller should fix the request, while -32603 means the server failed.
Checkpoint 5 of 5· Fill the gap
A user picks the code_review slash command, and the server answers prompts/get. Which field holds the filled-in template that the server returns?
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"resultType": "complete",
"description": "Code review prompt",
" ? ": [
{
"role": "user",
"content": {
"type": "text",
"text": "Please review this Python code:\ndef hello():\n print('world')"
}
}
]
}
}prompts/get fills the template with the user's arguments and returns a messages array. Each message has a role of user or assistant. A content array is what tools/call returns, structuredContent is the typed output of a tool, and contents is what resources/read returns.
Source: modelcontextprotocol.ioSources8
Sources
(8)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Contextual data attached and managed by the client”
↩︎ Three primitives, three different controllers“Functions exposed to the LLM to take actions”
↩︎ Key concept“Interactive templates invoked by user choice”
↩︎ Exam trap 1“Interactive templates invoked by user choice”
↩︎ Prediction“Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/mcpOfficial docs
“/plugin install mcp-server-dev@claude-plugins-official”
↩︎ Three primitives, three different controllers - 3.
“Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.”
↩︎ Three primitives, three different controllers“Access tokens MUST NOT be included in the URI query string”
↩︎ Three primitives, three different controllers“Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.”
↩︎ Exam trap 2 - 4.
“Servers SHOULD implement proper authentication for all connections”
↩︎ Three primitives, three different controllers - 5.
“Have a gateway call each tool with its own credential, and never pass the token on.”
↩︎ Three primitives, three different controllers - 6.
“Tool names SHOULD be between 1 and 128 characters in length (inclusive).”
↩︎ Tools: listed, called, and answered with typed results“Servers MUST provide structured results that conform to this schema.”
↩︎ Tools: listed, called, and answered with typed results“For authenticated servers, a handle is a name, not a capability.”
↩︎ Tools: listed, called, and answered with typed results“A call against an expired or unknown handle should return a tool execution error that says so”
↩︎ Tools: listed, called, and answered with typed results“For authenticated servers, a handle is a name, not a capability. The server should validate the caller’s authorization against the handle on every call.”
↩︎ Checkpoint - 7.
“Servers MUST sanitize file paths to prevent directory traversal attacks when serving file:// resources”
↩︎ Resources: context the client reads by URI“priority: A number from 0.0 to 1.0 indicating the importance of this resource.”
↩︎ Resources: context the client reads by URI - 8.
“Servers SHOULD validate prompt arguments before processing”
↩︎ Prompts: user-chosen templates that return messages“Missing required arguments: -32602 (Invalid params)”
↩︎ Prompts: user-chosen templates that return messages