What the MCP Server Configuration Builder does
This builder writes the JSON a Model Context Protocol server has to answer with - the server/discover or initialize result, and the tools/list, resources/list and prompts/list results - plus ready-to-paste client configuration for Claude Desktop, Claude Code and VS Code, and checks all of it against the MCP schema.
It follows the current specification revision, 2026-07-28, and can also produce the older handshake-based revisions (2025-11-25, 2025-06-18 and earlier) for servers that still have to talk to older clients. Everything is assembled in your browser; no server is started and nothing is sent anywhere.
How to use it
- Pick the protocol revision. Choose 2026-07-28 for a new server; pick 2025-11-25 or 2025-06-18 only if the clients you support have not moved on yet.
- Enter the server name and version. These become serverInfo - in
_meta["io.modelcontextprotocol/serverInfo"]for 2026-07-28, or the serverInfo field of the initialize result for older revisions. - Tick the capabilities the server really offers and paste each tool, resource, template and prompt as a JSON array. The examples show the expected shape, including annotations and an outputSchema.
- Describe how a client reaches the server: a local command for stdio, or a URL and headers for Streamable HTTP.
- Press Build and validate. Choose which output to view, copy or download it, and read the validation list before you ship.
Reading the results
Errors are breaches of a MUST or of a required field in the schema - a client may reject the result. Warnings are SHOULD-level rules, deprecated features or things that commonly cause trouble. Items marked as an A2Z check are our own advice (for example, a tool with no description), not protocol rules.
The protocol outputs are shown inside a JSON-RPC 2.0 response envelope with a placeholder id; your server will use the id of the request it is answering.
The client snippets are not part of MCP. Claude Desktop, Claude Code and VS Code each document their own file format, and the note above each snippet says which vendor it follows.
Worked example: a small weather server
A server called weather-server, version 1.2.0, offers two read-only tools (get_current and get_forecast), one resource and one resource template, and a packing_list prompt. It is started locally with npx -y weather-mcp-server --units metric and needs an API key.
On 2026-07-28 the builder produces a server/discover result with supportedVersions: ["2026-07-28"], capabilities {tools:{}, resources:{}, prompts:{}}, the serverInfo in _meta, and resultType, ttlMs and cacheScope on the discover result and each list result, because the current revision makes those results cacheable. Switching to 2025-06-18 turns the same data into an initialize result with protocolVersion, capabilities and serverInfo, and drops the cache fields.
The key is written as WEATHER_API_KEY=${WEATHER_API_KEY}, so no secret lands in the config file. Had it been pasted as a literal 40-character value, the builder would warn that config files are often committed to repositories.
What changed in 2026-07-28
The 2026-07-28 revision removed the initialize handshake. Each request now carries its protocol version, client identity and client capabilities in _meta, and a server must implement server/discover, which returns supportedVersions, capabilities, optional instructions and the serverInfo. Every result must include resultType, and discover and list results must say how long they may be cached (ttlMs) and whether the cache may be shared (cacheScope).
Capabilities gained an extensions map for opt-in features such as tasks, keyed by a reverse-DNS identifier like io.modelcontextprotocol/tasks. The logging capability is deprecated but kept for at least twelve months. A dual-era server can still answer initialize for legacy clients, which is why the builder can produce both shapes from one form.
Writing tools a model can use well
The schema only requires a tool name and an inputSchema whose root type is object. In practice the description does most of the work: the model decides which tool to call, and with which arguments, from the descriptions alone. Say what the tool does, when not to use it, and what each parameter means.
Annotations are hints for the client, not guarantees. With none set, the schema defaults treat a tool as able to modify its environment, possibly destructively, and to reach an open world, so many clients will ask the user before every call. Mark genuinely read-only tools with readOnlyHint: true. Tool names should be 1 to 128 characters of letters, digits, underscore, hyphen and dot - a SHOULD rule since 2025-11-25.
Limitations: what the result does not prove
- It validates structure, not behaviour. A clean result means the declarations follow the schema; it cannot tell whether your server actually returns what it declares or handles errors correctly.
- The JSON Schema inside inputSchema and outputSchema is checked for the MCP-specific rules (root type object, required names, x-mcp-header) but is not fully validated as JSON Schema 2020-12. Use a JSON Schema validator for that.
- Client configuration formats change more often than the protocol. Check the client's own documentation if a snippet is rejected.
- It does not generate server code, run a server, or test a transport.
Privacy: where your data goes
Everything you paste, type or drop is processed in this browser tab. It is not uploaded, logged, stored or sent to analytics. Session recording and tag-manager scripts are switched off on this page.
Standards and sources
- Model Context Protocol specification 2026-07-28 - checked 19 Sep 2026
- MCP versioning and backward compatibility
- MCP server/discover
- MCP specification 2025-06-18
- Claude Code - MCP configuration
- VS Code - MCP configuration reference
Frequently asked questions
What goes in an MCP server's initialize response?
For revisions up to 2025-11-25, the initialize result carries protocolVersion (the revision the server will speak), capabilities (an object per feature it offers, such as tools or resources), serverInfo with name and version, and optional instructions for the model. In 2026-07-28 the same information moves to the server/discover result.
Does MCP still use an initialize handshake?
Not in the current revision. 2026-07-28 is stateless: every request states its protocol version in _meta, and servers must implement server/discover instead. Legacy clients still send initialize, so a server that wants to serve both answers both - which this builder can generate from the same form.
Why does my capability need to be an empty object rather than true?
The schema types each server capability as an object, so support is declared with {} or with an object of sub-flags such as {"listChanged": true}. A bare true is the wrong type, and strict clients can reject the whole result because of it.
Where does claude_desktop_config.json live and what does it contain?
Claude Desktop reads an mcpServers map from claude_desktop_config.json in its application settings folder; each entry gives the command, args and optional env to launch a local stdio server. It is Anthropic's client convention, not part of the MCP specification, and remote servers are added as connectors instead.
What is the difference between .mcp.json and .vscode/mcp.json?
Claude Code's project file .mcp.json uses a top-level mcpServers map and supports ${VAR} expansion; VS Code's .vscode/mcp.json uses a top-level servers map with an explicit type of stdio or http and an optional inputs list for prompted secrets. Both describe how to reach the same server.
Should I put API keys in the MCP config file?
Avoid it. Config files are easy to commit or share by accident. Use a variable reference such as ${API_KEY} where the client expands them, or the client's own secret prompt, and keep the real value in your environment or keychain. The builder warns when a value looks like a literal secret.
What do ttlMs and cacheScope mean in MCP 2026-07-28?
They tell the client how long a discover or list result stays fresh and who may share the cached copy. ttlMs is milliseconds (0 means always re-fetch); cacheScope public means the result has no user-specific data and a shared cache may serve it, private means per authorization context only.
Last reviewed by the A2Z.Tools team against the sources listed above.
