Merge branch 'main' into localden/auth-guide

Author: localden

CONTRIBUTING.md

@@ -18,37 +18,38 @@ The following software is required to work on the spec:
 ### Getting Started
 
 1. [Fork the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
+
 2. Clone your fork:
 
-```bash
-git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git
-cd modelcontextprotocol
-```
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/modelcontextprotocol.git
+   cd modelcontextprotocol
+   ```
 
 3. Install dependencies:
 
-```bash
-nvm install  # install correct Node version
-npm install  # install dependencies
-```
+   ```bash
+   nvm install  # install correct Node version
+   npm install  # install dependencies
+   ```
 
-## Schema changes
+4. Create a new branch:
 
-Note that schema changes are made to `schema.ts`, and `schema.json` is generated from
-`schema.ts`.
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
 
-1. Create a new branch:
+## Schema changes
+
+Schema changes go in `schema/draft/schema.ts`. To validate your changes, run:
 
 ```bash
-git checkout -b feature/your-feature-name
+npm run check:schema:ts
 ```
 
-2. Make your changes.
-
-3. Validate schema changes and generate `schema.json`:
+`schema/draft/schema.json` and `docs/specification/draft/schema.mdx` are generated from `schema/draft/schema.ts`; do not edit them directly. To generate them, run:
 
 ```bash
-npm run check:schema:ts
 npm run generate:schema
 ```
 

MAINTAINERS.md

@@ -71,6 +71,11 @@ This document lists current maintainers in the Model Context Protocol project.
 
 - [Alex Hancock](https://github.com/alexhancock)
 
+### PHP SDK
+
+- [Kyrian Obikwelu](https://github.com/CodeWithKyrian)
+- [Christopher Hertel](https://github.com/chr-hertel)
+
 ## Project Maintainers
 
 ### use-mcp
@@ -126,6 +131,10 @@ This document lists current maintainers in the Model Context Protocol project.
 - [Harald Kirschner](https://github.com/digitarald)
 - [Connor Peet](https://github.com/connor4312)
 
+### Financial Services Interest Group
+
+- [Sambhav Kothari](https://github.com/sambhav)
+
 ### Transports Interest Group
 
 - [Kurtis Van Gent](https://github.com/kurtisvg)
@@ -137,8 +146,10 @@ This document lists current maintainers in the Model Context Protocol project.
 
 - [Nick Cooper](https://github.com/nicknotfun)
 
-### Long-Running / Async Tool Calls Working Group
+### Agents Working Group
 
+- [Peter Alexander](https://github.com/pja-ant)
+- [Luca Chang](https://github.com/LucaButBoring)
 - [Inna Harper](https://github.com/ihrpr)
 
 ## About This Document

docs/clients.mdx

@@ -22,6 +22,12 @@ These groups exist to:
 
 ## Mechanisms
 
+## Meeting Calendar
+
+All Interest Group and Working Group meetings are published on the public MCP community calendar at [meet.modelcontextprotocol.io](https://meet.modelcontextprotocol.io/).
+
+Facilitators are responsible for posting their meeting schedules to this calendar in advance to ensure discoverability and enable broader community participation.
+
 ### Interest Groups (IGs)
 
 **Goal:** Facilitate discussion and knowledge-sharing among MCP contributors who share interests in a specific MCP sub-topic or context. The primary focus is on identifying and gathering problems that may be worth addressing through SEPs or other community artifacts, while encouraging open exploration of protocol issues and opportunities.
@@ -30,6 +36,8 @@ These groups exist to:
 
 - Regular conversations in the Interest Group Discord channel
 - **AND/OR** a recurring live meeting regularly attended by Interest Group members
+- Meeting dates and times published in advance on the [MCP community calendar](https://meet.modelcontextprotocol.io/) when applicable, and tagged with their primary topic and interest group Discord channel name (e.g. `auth-ig`)
+- Notes publicly shared after meetings, as a GitHub issue ([example](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1629)) and/or public Google Doc
 
 **Examples**:
 
@@ -68,6 +76,8 @@ Participation in an Interest Group (IG) is not required to start a Working Group
 
 - Meaningful progress towards at least one SEP or spec-related implementation **OR** hold maintenance responsibilities for a project (e.g., Inspector, Registry, SDKs)
 - Facilitators are responsible for keeping track of progress and communicating status when appropriate
+- Meeting dates and times published in advance on the [MCP community calendar](https://meet.modelcontextprotocol.io/) when applicable, and tagged with their primary topic and working group Discord channel name (e.g. `agents-wg`)
+- Notes publicly shared after meetings, as a GitHub issue ([example](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1629)) and/or public Google Doc
 
 **Examples**:
 

docs/community/working-interest-groups.mdx

@@ -377,10 +377,6 @@
       "source": "/docs/concepts",
       "destination": "/docs/learn/architecture"
     },
-    {
-      "source": "/docs/tools",
-      "destination": "/legacy/tools/inspector"
-    },
     {
       "source": "/docs/tutorials/use-remote-mcp-server",
       "destination": "/docs/develop/connect-remote-servers"

docs/docs.json

@@ -392,6 +392,10 @@ When you submit a query:
    - Validate server responses
    - Be cautious with tool permissions
 
+4. **Tool Names**
+   - Tool names can be validated according to the format specified [here](/specification/draft/server/tools#tool-names)
+   - If a tool name conforms to the specified format, it should not fail validation by an MCP client
+
 ## Troubleshooting
 
 ### Server Path Issues

docs/docs/develop/build-client.mdx

@@ -59,6 +59,7 @@ Writing to stdout will corrupt the JSON-RPC messages and break your server.
 ### Best Practices
 
 1. Use a logging library that writes to stderr or files.
+1. Tool names should follow the format specified [here](/specification/draft/server/tools#tool-names).
 
 ### Quick Examples
 
@@ -1856,6 +1857,17 @@ tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
 2. Make sure the path to your project is absolute and not relative
 3. Restart Claude for Desktop completely
 
+<Warning>
+
+To properly restart Claude for Desktop, you must fully quit the application:
+
+- **Windows**: Right-click the Claude icon in the system tray (which may be hidden in the "hidden icons" menu) and select "Quit" or "Exit".
+- **macOS**: Use Cmd+Q or select "Quit Claude" from the menu bar.
+
+Simply closing the window does not fully quit the application, and your MCP server configuration changes will not take effect.
+
+</Warning>
+
 **Tool calls failing silently**
 
 If Claude attempts to use the tools but they fail:

docs/docs/develop/build-server.mdx

@@ -55,13 +55,6 @@ graph TB
     Client1 ---|"One-to-one<br/>connection"| Server1
     Client2 ---|"One-to-one<br/>connection"| Server2
     Client3 ---|"One-to-one<br/>connection"| Server3
-
-    style Client1 fill:#e1f5fe
-    style Client2 fill:#e1f5fe
-    style Client3 fill:#e1f5fe
-    style Server1 fill:#f3e5f5
-    style Server2 fill:#f3e5f5
-    style Server3 fill:#f3e5f5
 ```
 
 Note that **MCP server** refers to the program that serves context data, regardless of

docs/docs/learn/architecture.mdx

@@ -14,7 +14,7 @@ In addition to making use of context provided by servers, clients may provide se
 | Feature         | Explanation                                                                                                                                                                                       | Example                                                                                                                                |
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | **Sampling**    | Sampling allows servers to request LLM completions through the client, enabling an agentic workflow. This approach puts the client in complete control of user permissions and security measures. | A server for booking travel may send a list of flights to an LLM and request that the LLM pick the best flight for the user.           |
-| **Roots**       | Roots allow clients to specify which files servers can access, guiding them to relevant directories while maintaining security boundaries.                                                        | A server for booking travel may be given access to a specific directory, from which it can read a user's calendar.                     |
+| **Roots**       | Roots allow clients to specify which directories servers should focus on, communicating intended scope through a coordination mechanism.                                                          | A server for booking travel may be given access to a specific directory, from which it can read a user's calendar.                     |
 | **Elicitation** | Elicitation enables servers to request specific information from users during interactions, providing a structured way for servers to gather information on demand.                               | A server booking travel may ask for the user's preferences on airplane seats, room type or their contact number to finalise a booking. |
 
 ### Elicitation
@@ -108,7 +108,7 @@ Roots define filesystem boundaries for server operations, allowing clients to sp
 
 #### Overview
 
-Roots are a mechanism for clients to communicate filesystem access boundaries to servers. They consist of file URIs that indicate directories where servers can operate, helping servers understand the scope of available files and folders. Rather than giving servers unrestricted filesystem access, roots guide them to relevant working directories while maintaining security boundaries.
+Roots are a mechanism for clients to communicate filesystem access boundaries to servers. They consist of file URIs that indicate directories where servers can operate, helping servers understand the scope of available files and folders. Rather than giving servers unrestricted filesystem access, roots guide them to relevant working directories. While roots communicate intended boundaries, actual security is always maintained by the client's access controls.
 
 **Root structure:**
 
@@ -121,8 +121,6 @@ Roots are a mechanism for clients to communicate filesystem access boundaries to
 
 Roots are exclusively filesystem paths and always use the `file://` URI scheme. They help servers understand project boundaries, workspace organization, and accessible directories. The roots list can be updated dynamically as users work with different projects or folders, with servers receiving notifications through `roots/list_changed` when boundaries change.
 
-It's important to note that while roots provide guidance to servers about where to operate, the client is always in full control of file access. Roots simply communicate intended boundaries—actual file access is always mediated by the client's security policies.
-
 #### Example: Travel Planning Workspace
 
 A travel agent working with multiple client trips benefits from roots to organize filesystem access. Consider a workspace with different directories for various aspects of travel planning.
@@ -133,15 +131,23 @@ The client provides filesystem roots to the travel planning server:
 - `file:///Users/agent/travel-templates` - Reusable itinerary templates and resources
 - `file:///Users/agent/client-documents` - Client passports and travel documents
 
-When the agent creates a Barcelona itinerary, the server works within these boundaries—accessing templates, saving the new itinerary, and referencing client documents. It cannot access files outside these roots. Servers typically access files within roots by using relative paths from the root directories or by utilizing file search tools that respect the root boundaries.
+When the agent creates a Barcelona itinerary, well-behaved servers respect these boundaries—accessing templates, saving the new itinerary, and referencing client documents within the specified roots. Servers typically access files within roots by using relative paths from the root directories or by utilizing file search tools that respect the root boundaries.
 
 If the agent opens an archive folder like `file:///Users/agent/archive/2023-trips`, the client updates the roots list via `roots/list_changed`.
 
+For a complete implementation of a server that respects roots, see the [filesystem server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) in the official servers repository.
+
+#### Design Philosophy
+
+Roots serve as a coordination mechanism between clients and servers, not a security boundary. The specification requires that servers "SHOULD respect root boundaries," and not that they "MUST enforce" them, because servers run code the client cannot control. This design is pragmatic: clients enforce security while roots communicate intent.
+
+Roots work best when servers are trusted or vetted, users understand their advisory nature, and the goal is preventing accidents rather than stopping malicious behavior. They excel at context scoping (telling servers where to focus), accident prevention (helping well-behaved servers stay in bounds), and workflow organization (such as managing project boundaries automatically).
+
 #### User Interaction Model
 
 Roots are typically managed automatically by host applications based on user actions, though some applications may expose manual root management:
 
-**Automatic root detection**: When users open folders, clients automatically expose them as roots. Opening a travel workspace gives servers access to itineraries and documents within that directory.
+**Automatic root detection**: When users open folders, clients automatically expose them as roots. Opening a travel workspace allows the client to expose that directory as a root, helping servers understand which itineraries and documents are in scope for the current work.
 
 **Manual root configuration**: Advanced users can specify roots through configuration. For example, adding `/travel-templates` for reusable resources while excluding directories with financial records.