MCP Builder
Principles for building MCP servers against the current spec.
Spec baseline: MCP 2026-07-28 (previous: 2025-11-25). Always confirm the latest
revision at https://modelcontextprotocol.io/specification/latest and its changelog
before relying on version-specific details.
Deep dives: references/protocol-and-transports.md
(stateless model, transports, version negotiation, migration) and
references/authorization-and-security.md
(OAuth 2.1, protected resource metadata, client registration, threats).
1. What MCP Is
MCP is an open JSON-RPC 2.0 protocol that lets AI applications (hosts/clients) use
capabilities exposed by servers.
| Primitive |
Controlled by |
Purpose |
| Tools |
Model |
Functions the model can invoke (side effects allowed) |
| Resources |
Application |
Context data addressed by URI (files, records, docs) |
| Prompts |
User |
Reusable, parameterized prompt templates / workflows |
Client-side features a server can ask for: elicitation (ask the user for input).
Roots, Sampling and Logging are deprecated in 2026-07-28 — do not build new
dependencies on them (pass paths as tool params; call LLM APIs directly; log to
stderr or OpenTelemetry).
What changed in 2026-07-28 (high impact)
| Change |
Consequence for servers |
Protocol is stateless: no initialize handshake, no Mcp-Session-Id |
Each request carries protocol version + client capabilities in _meta; never keep per-connection state |
server/discover RPC (MUST implement) |
Advertise supported versions, capabilities, identity |
| Multi Round-Trip Requests (MRTR) |
Need user input mid-call? Return resultType: "input_required" with inputRequests; client retries with inputResponses |
subscriptions/listen replaces GET stream + resources/subscribe |
Change notifications only on opted-in listen streams |
Tasks moved to an extension (io.modelcontextprotocol/tasks) |
Long-running work = opt-in extension |
| Client ID Metadata Documents preferred; DCR deprecated |
See auth reference |
SDKs may lag the spec — check your SDK's release notes for which protocol versions it
implements, and support older clients via server/discover/version negotiation.
2. Server Architecture
Transports (standard)
| Transport |
Use |
| stdio |
Local server launched as a subprocess by the client; JSON-RPC over stdin/stdout. Logs go to stderr only |
| Streamable HTTP |
Remote server; single MCP endpoint accepting POST, response as JSON or an SSE stream |
- HTTP+SSE (the old two-endpoint transport) is deprecated since 2025-03-26 —
migrate to Streamable HTTP. "SSE" now only means the response-streaming mode
inside Streamable HTTP.
- WebSocket is not a standard MCP transport (custom transports are allowed but
not interoperable).
Statelessness rules
- No protocol session:
tools/list, resources/list, prompts/list must not vary
per connection (they MAY vary by the caller's authorization).
- Need state across calls (cart, browser context, transaction)? Return an explicit,
opaque, high-entropy handle from a "create" tool and accept it as an argument.
Bind it server-side to the authenticated user; possession of a handle is never
authentication. Document its lifetime in the tool description.
- Horizontal scaling is straightforward: any replica can serve any request.
Project layout (TypeScript example)
my-mcp-server/
├── src/
│ ├── index.ts # server + transport wiring
│ ├── tools/ # one module per tool (schema + handler)
│ └── resources/
├── test/
├── package.json
└── tsconfig.json
3. Tool Design
Definition fields
| Field |
Notes |
name |
1–128 chars, [A-Za-z0-9_.-], unique per server, action-oriented (create_issue) |
title |
Optional human-friendly display name |
description |
What it does, when to use it, side effects, limits — the model reads this |
inputSchema |
JSON Schema (2020-12 default); type: object; describe every property; mark required; no-arg tools: { "type": "object", "additionalProperties": false } |
outputSchema |
Optional JSON Schema for structuredContent; if present, results MUST conform |
annotations |
Behavior hints (below) |
icons |
Optional UI icons |
Results
content: unstructured blocks — text, image, audio (base64 + mimeType),
resource_link, embedded resource.
structuredContent: any JSON value matching outputSchema. For backwards
compatibility also return the serialized JSON in a text block.
- Errors the model can fix (bad date, not found, upstream API failure) → a normal
result with
isError: true and an actionable message. Malformed requests / unknown
tool → JSON-RPC protocol error.
Annotations (hints, not guarantees)
| Hint |
Meaning |
readOnlyHint |
Does not modify its environment |
destructiveHint |
May perform destructive updates (meaningful when not read-only) |
idempotentHint |
Repeating the call with same args has no extra effect |
openWorldHint |
Interacts with external entities (web, third-party APIs) |
Clients MUST treat annotations as untrusted unless the server is trusted — never rely
on them as a security control.
Design principles
| Principle |
Practice |
| Task-shaped, not API-shaped |
Prefer schedule_meeting over thin wrappers of every endpoint |
| Few, focused tools |
Large tool lists cost context and confuse selection |
| Bounded output |
Paginate, truncate, offer limit/filters; return IDs + summaries |
| Deterministic order |
Return tools/list in stable order (cache-friendly) |
| No secrets in args |
Never mark sensitive params with x-mcp-header (headers are visible to proxies) |
4. Resources
| Pattern |
Example |
| Direct resource |
docs://readme, file:///project/README.md |
| Resource template (RFC 6570) |
users://{userId}/profile |
resources/list, resources/templates/list, resources/read; results carry
ttlMs + cacheScope caching hints in 2026-07-28.
- Use
mimeType; text vs base64 blob. Annotations: audience, priority,
lastModified.
- Unknown resource → JSON-RPC
-32602 (Invalid Params) in 2026-07-28.
- Change notifications are delivered via
subscriptions/listen.
5. Prompts
prompts/list + prompts/get with typed arguments; return a list of messages.
- Use for user-invoked workflows (slash commands), not for hidden instructions.
6. Elicitation
- Ask the user for missing input mid-operation. In 2026-07-28 this is an MRTR
inputRequests entry (method: "elicitation/create"), answered on the client's retry.
- Form mode: flat JSON Schema of primitives; for non-sensitive data only.
- URL mode: send the user to a URL (OAuth to a third party, payment, API-key entry)
— sensitive data never passes through the MCP client.
- Handle
accept / decline / cancel; carry your own correlation data in
requestState.
7. Authorization (HTTP transports)
- Optional, but if a remote server is protected: it acts as an OAuth 2.1 resource
server.
- MUST publish Protected Resource Metadata (RFC 9728,
/.well-known/oauth-protected-resource) and return 401 with
WWW-Authenticate: Bearer resource_metadata="…", scope="…".
- Validate every token: issuer, expiry, and audience = this server (RFC 8707
resource indicators). Insufficient scope →
403 + error="insufficient_scope".
- Clients register via Client ID Metadata Documents (preferred), pre-registration,
or Dynamic Client Registration (deprecated, back-compat only).
- stdio servers do not use this flow — read credentials from the environment.
Details: references/authorization-and-security.md.
8. Security Checklist
9. Official SDKs
Tier 1: TypeScript (@modelcontextprotocol/sdk), Python (mcp, includes FastMCP-style
server API), C#, Go, Rust, Ruby. Tier 2: Java. Tier 3: Swift, PHP, Kotlin.
List and tiers: https://modelcontextprotocol.io/docs/sdk. Prefer an official SDK over
hand-rolled JSON-RPC.
10. Configuration (stdio clients)
| Field |
Purpose |
command |
Executable to run |
args |
Command arguments |
env |
Environment variables (credentials for stdio servers) |
Remote servers are configured by URL (Streamable HTTP endpoint); the client handles OAuth.
11. Testing
| Layer |
How |
| Unit |
Tool handlers as plain functions; schema validation of inputs/outputs |
| Protocol |
SDK in-memory/client transport: list → call → assert structuredContent |
| Interactive |
MCP Inspector: npx @modelcontextprotocol/inspector <command> (stdio) or point it at the HTTP URL |
| Auth |
401 + WWW-Authenticate, wrong-audience token rejected, 403 on missing scope |
| Model-level |
Evaluate with realistic prompts that the model picks the right tool with right args |
12. Best Practices Checklist
Remember: the model only knows what your names, descriptions and schemas tell it.
Keep tools few, focused, safe by default, and stateless.
1---2name: mcp-builder3description: "MCP server tool design, schemas, errors and security. Use when creating or reviewing an MCP server or its tool definitions."4allowed-tools: Read Write Edit Glob Grep5metadata:6 source: https://skillmd.com/skills/jeffersonvalente/mcp-builder7---89# MCP Builder1011> Principles for building MCP servers against the current spec.12> Spec baseline: **MCP 2026-07-28** (previous: 2025-11-25). Always confirm the latest13> revision at <https://modelcontextprotocol.io/specification/latest> and its changelog14> before relying on version-specific details.1516Deep dives: [references/protocol-and-transports.md](references/protocol-and-transports.md)17(stateless model, transports, version negotiation, migration) and18[references/authorization-and-security.md](references/authorization-and-security.md)19(OAuth 2.1, protected resource metadata, client registration, threats).2021---2223## 1. What MCP Is2425MCP is an open JSON-RPC 2.0 protocol that lets AI applications (hosts/clients) use26capabilities exposed by **servers**.2728| Primitive | Controlled by | Purpose |29|-----------|---------------|---------|30| **Tools** | Model | Functions the model can invoke (side effects allowed) |31| **Resources** | Application | Context data addressed by URI (files, records, docs) |32| **Prompts** | User | Reusable, parameterized prompt templates / workflows |3334Client-side features a server can ask for: **elicitation** (ask the user for input).35Roots, Sampling and Logging are **deprecated** in 2026-07-28 — do not build new36dependencies on them (pass paths as tool params; call LLM APIs directly; log to37`stderr` or OpenTelemetry).3839### What changed in 2026-07-28 (high impact)4041| Change | Consequence for servers |42|--------|-------------------------|43| Protocol is **stateless**: no `initialize` handshake, no `Mcp-Session-Id` | Each request carries protocol version + client capabilities in `_meta`; never keep per-connection state |44| `server/discover` RPC (MUST implement) | Advertise supported versions, capabilities, identity |45| Multi Round-Trip Requests (MRTR) | Need user input mid-call? Return `resultType: "input_required"` with `inputRequests`; client retries with `inputResponses` |46| `subscriptions/listen` replaces GET stream + `resources/subscribe` | Change notifications only on opted-in listen streams |47| Tasks moved to an extension (`io.modelcontextprotocol/tasks`) | Long-running work = opt-in extension |48| Client ID Metadata Documents preferred; DCR deprecated | See auth reference |4950SDKs may lag the spec — check your SDK's release notes for which protocol versions it51implements, and support older clients via `server/discover`/version negotiation.5253---5455## 2. Server Architecture5657### Transports (standard)5859| Transport | Use |60|-----------|-----|61| **stdio** | Local server launched as a subprocess by the client; JSON-RPC over stdin/stdout. Logs go to **stderr** only |62| **Streamable HTTP** | Remote server; single MCP endpoint accepting POST, response as JSON or an SSE stream |6364- HTTP+SSE (the old two-endpoint transport) is **deprecated** since 2025-03-26 —65 migrate to Streamable HTTP. "SSE" now only means the response-streaming mode66 *inside* Streamable HTTP.67- WebSocket is **not** a standard MCP transport (custom transports are allowed but68 not interoperable).6970### Statelessness rules7172- No protocol session: `tools/list`, `resources/list`, `prompts/list` must not vary73 per connection (they MAY vary by the caller's authorization).74- Need state across calls (cart, browser context, transaction)? Return an explicit,75 opaque, high-entropy **handle** from a "create" tool and accept it as an argument.76 Bind it server-side to the authenticated user; possession of a handle is never77 authentication. Document its lifetime in the tool description.78- Horizontal scaling is straightforward: any replica can serve any request.7980### Project layout (TypeScript example)8182```83my-mcp-server/84├── src/85│ ├── index.ts # server + transport wiring86│ ├── tools/ # one module per tool (schema + handler)87│ └── resources/88├── test/89├── package.json90└── tsconfig.json91```9293---9495## 3. Tool Design9697### Definition fields9899| Field | Notes |100|-------|-------|101| `name` | 1–128 chars, `[A-Za-z0-9_.-]`, unique per server, action-oriented (`create_issue`) |102| `title` | Optional human-friendly display name |103| `description` | What it does, when to use it, side effects, limits — the model reads this |104| `inputSchema` | JSON Schema (2020-12 default); `type: object`; describe every property; mark `required`; no-arg tools: `{ "type": "object", "additionalProperties": false }` |105| `outputSchema` | Optional JSON Schema for `structuredContent`; if present, results MUST conform |106| `annotations` | Behavior hints (below) |107| `icons` | Optional UI icons |108109### Results110111- `content`: unstructured blocks — `text`, `image`, `audio` (base64 + `mimeType`),112 `resource_link`, embedded `resource`.113- `structuredContent`: any JSON value matching `outputSchema`. For backwards114 compatibility also return the serialized JSON in a text block.115- Errors the model can fix (bad date, not found, upstream API failure) → a normal116 result with `isError: true` and an actionable message. Malformed requests / unknown117 tool → JSON-RPC protocol error.118119### Annotations (hints, not guarantees)120121| Hint | Meaning |122|------|---------|123| `readOnlyHint` | Does not modify its environment |124| `destructiveHint` | May perform destructive updates (meaningful when not read-only) |125| `idempotentHint` | Repeating the call with same args has no extra effect |126| `openWorldHint` | Interacts with external entities (web, third-party APIs) |127128Clients MUST treat annotations as untrusted unless the server is trusted — never rely129on them as a security control.130131### Design principles132133| Principle | Practice |134|-----------|----------|135| Task-shaped, not API-shaped | Prefer `schedule_meeting` over thin wrappers of every endpoint |136| Few, focused tools | Large tool lists cost context and confuse selection |137| Bounded output | Paginate, truncate, offer `limit`/filters; return IDs + summaries |138| Deterministic order | Return `tools/list` in stable order (cache-friendly) |139| No secrets in args | Never mark sensitive params with `x-mcp-header` (headers are visible to proxies) |140141---142143## 4. Resources144145| Pattern | Example |146|---------|---------|147| Direct resource | `docs://readme`, `file:///project/README.md` |148| Resource template (RFC 6570) | `users://{userId}/profile` |149150- `resources/list`, `resources/templates/list`, `resources/read`; results carry151 `ttlMs` + `cacheScope` caching hints in 2026-07-28.152- Use `mimeType`; text vs base64 `blob`. Annotations: `audience`, `priority`,153 `lastModified`.154- Unknown resource → JSON-RPC `-32602` (Invalid Params) in 2026-07-28.155- Change notifications are delivered via `subscriptions/listen`.156157## 5. Prompts158159- `prompts/list` + `prompts/get` with typed `arguments`; return a list of messages.160- Use for user-invoked workflows (slash commands), not for hidden instructions.161162## 6. Elicitation163164- Ask the user for missing input mid-operation. In 2026-07-28 this is an MRTR165 `inputRequests` entry (`method: "elicitation/create"`), answered on the client's retry.166- **Form mode**: flat JSON Schema of primitives; for non-sensitive data only.167- **URL mode**: send the user to a URL (OAuth to a third party, payment, API-key entry)168 — sensitive data never passes through the MCP client.169- Handle `accept` / `decline` / `cancel`; carry your own correlation data in170 `requestState`.171172---173174## 7. Authorization (HTTP transports)175176- Optional, but if a remote server is protected: it acts as an **OAuth 2.1 resource177 server**.178- MUST publish **Protected Resource Metadata** (RFC 9728,179 `/.well-known/oauth-protected-resource`) and return `401` with180 `WWW-Authenticate: Bearer resource_metadata="…", scope="…"`.181- Validate every token: issuer, expiry, and **audience = this server** (RFC 8707182 resource indicators). Insufficient scope → `403` + `error="insufficient_scope"`.183- Clients register via **Client ID Metadata Documents** (preferred), pre-registration,184 or Dynamic Client Registration (deprecated, back-compat only).185- **stdio servers do not use this flow** — read credentials from the environment.186187Details: [references/authorization-and-security.md](references/authorization-and-security.md).188189---190191## 8. Security Checklist192193- [ ] **No token passthrough**: never accept tokens not issued for this server, never194 forward the client's token downstream — obtain separate upstream credentials195- [ ] Least privilege: minimal scopes, minimal upstream API permissions, read-only by default196- [ ] Validate every input against the schema *and* business rules (paths, URLs, SQL, shell)197- [ ] Sanitize outputs; treat upstream data as untrusted (prompt injection via tool results)198- [ ] Rate-limit tool calls; enforce timeouts and output size limits199- [ ] Secrets from env/secret manager; never logged or returned200- [ ] Local HTTP servers: bind to `127.0.0.1`, validate `Origin` (DNS rebinding), require auth201- [ ] Human-in-the-loop for destructive tools (set `destructiveHint`, clear descriptions)202- [ ] Audit log of tool invocations (no secrets/PII)203204---205206## 9. Official SDKs207208Tier 1: TypeScript (`@modelcontextprotocol/sdk`), Python (`mcp`, includes FastMCP-style209server API), C#, Go, Rust, Ruby. Tier 2: Java. Tier 3: Swift, PHP, Kotlin.210List and tiers: <https://modelcontextprotocol.io/docs/sdk>. Prefer an official SDK over211hand-rolled JSON-RPC.212213## 10. Configuration (stdio clients)214215| Field | Purpose |216|-------|---------|217| `command` | Executable to run |218| `args` | Command arguments |219| `env` | Environment variables (credentials for stdio servers) |220221Remote servers are configured by URL (Streamable HTTP endpoint); the client handles OAuth.222223---224225## 11. Testing226227| Layer | How |228|-------|-----|229| Unit | Tool handlers as plain functions; schema validation of inputs/outputs |230| Protocol | SDK in-memory/client transport: list → call → assert `structuredContent` |231| Interactive | **MCP Inspector**: `npx @modelcontextprotocol/inspector <command>` (stdio) or point it at the HTTP URL |232| Auth | 401 + `WWW-Authenticate`, wrong-audience token rejected, 403 on missing scope |233| Model-level | Evaluate with realistic prompts that the model picks the right tool with right args |234235---236237## 12. Best Practices Checklist238239- [ ] Targets a named spec revision; `server/discover` advertises supported versions240- [ ] stdio or Streamable HTTP only (no legacy HTTP+SSE, no WebSocket)241- [ ] No per-connection state; explicit handles for cross-call state242- [ ] Clear names, rich descriptions, complete `inputSchema`243- [ ] `outputSchema` + `structuredContent` for machine-readable results244- [ ] Accurate annotations245- [ ] `isError: true` with actionable messages for recoverable failures246- [ ] Authorization per spec for remote servers; no token passthrough247- [ ] Tested in MCP Inspector and with an automated client248249---250251> **Remember:** the model only knows what your names, descriptions and schemas tell it.252> Keep tools few, focused, safe by default, and stateless.