Encourage title properties/usage for objects/resources likely t… #663

ZachGerman · 2025-06-06T06:20:46Z

Encourage UI-friendly naming by introducing a dedicated optional title property across the specification and updating all related examples to include it.

Added optional title field to resource, tool, prompt, clientInfo, and serverInfo definitions in the spec.
Updated JSON examples to include title entries where they're likely to be used.

Motivation and Context

By introducing title as a dedicated property, we ensure clarity and consistency in how data is surfaced to end users, improving both developer experience and user-facing usability as the protocol evolves.

Breaking Changes

Will users need to update their code or configurations? No. According to the language added to the spec, "if no title is provided, name should be used for display purposes". Thus, implementations currently leveraging name variables for display will be preserved.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

To be added to docs if/when this PR is published to an official spec version:

Naming conventions:

Objects with names expose two distinct properties: name and title. The name is intended for programmatic or logical use, while title is intended for UI and end-user contexts — optimized to be human-readable and easily understood, even by those unfamiliar with domain-specific terminology.

bhosmer-ant · 2025-06-10T04:11:49Z

Hi @ZachGerman - interested in your thoughts on a couple of things, just thinking out loud:

the "just use name if displayName is not provided" is nice for new client / old server compatibility. For old client / new server situations, it will mean tool names might be less readable than previously. I don't think this is a dealbreaker, but wanted to flag it.
wonder if you've thought about when to use displayName vs. annotations.title for tools. We might want to give some guidance about that in the new language.

schema/draft/schema.ts

connor4312

MCP already uses the title for the "displayName" in ToolAnnotations.title. Could we normalize one direction or the other?

connor4312 · 2025-06-10T20:33:49Z

docs/specification/draft/server/tools.mdx

 ```json
 {
  "name": "get_weather_data",
+  "displayName": "Weather Data Retriever",


This doesn't appear to be represented in the spec change and is duplicative with existing ToolAnnotations.title

bhosmer-ant · 2025-06-11T16:46:49Z

Hi @ZachGerman - this is definitely a useful addition and we'd like to add it to the draft spec, but with the following changes:

instead of adding displayName as a top-level property, create a BaseMetadata interface that contains name and title (rather than displayName)
for any type that contains name, inherit from that interface instead. (This will give us a place to make further additions later.)
for the documentation (in addition to changing displayName to title globally) we'd want to add language in Tool noting that in addition to the "first title then fall back to name" precedence order you specify elsewhere, for tools it should be "first title then annotations.title then name"

Realize this is a nontrivial set of edits and we're on a fairly tight schedule for the spec release, so if you don't have time/bandwidth in the next day or so we're happy to make the changes. Just LMK!

ZachGerman · 2025-06-11T21:31:51Z

Hi @ZachGerman - this is definitely a useful addition and we'd like to add it to the draft spec, but with the following changes:
* instead of adding `displayName` as a top-level property, create a `BaseMetadata` interface that contains `name` and `title` (rather than `displayName`)

* for any type that contains `name`, inherit from that interface instead. (This will give us a place to make further additions later.)

* for the documentation (in addition to changing `displayName` to `title` globally) we'd want to add language in `Tool` noting that in addition to the "first `title` then fall back to `name`" precedence order you specify elsewhere, for tools it should be "first `title` then `annotations.title` then `name`"
Realize this is a nontrivial set of edits and we're on a fairly tight schedule for the spec release, so if you don't have time/bandwidth in the next day or so we're happy to make the changes. Just LMK!

Done. Please let me know if anything else needs changed. I'm on-call this week, so I won't finish the server transport until next week, but this PR is small enough to keep up with during my on-call.

…epresented in a UI

bhosmer-ant · 2025-06-11T21:40:02Z

Awesome! Will review shortly but also please fix the merge conflicts when you have a chance. Thanks for the quick turnaround!

bhosmer-ant · 2025-06-11T22:38:35Z

Ugh sorry to do this to you but it looks like you need to rerun npm run generate:json 🙏 (also I'm not sure why the PR is still showing "out of date with the base branch" after your merge, but as long as there are no conflicts it should be innocuous)

ZachGerman · 2025-06-11T23:23:30Z

Ugh sorry to do this to you but it looks like you need to rerun npm run generate:json 🙏 (also I'm not sure why the PR is still showing "out of date with the base branch" after your merge, but as long as there are no conflicts it should be innocuous)

Should be fixed now.

bhosmer-ant · 2025-06-12T02:11:23Z

Hi @ZachGerman - had to make one change, Root.name was a different beast than the rest (optional, so making it mandatory would be bc-breaking, and paired with a URI, which arguably can serve as a machine-friendly id). Also it's not in your original list of candidates, so I suspect it might've been an accidental change.

Having pushed the change I can't merge it, but it should go in shortly. Thanks again for doing this!

bhosmer-ant

LGTM!

ihrpr

do we also need to update PromptReference?

ihrpr · 2025-06-12T08:40:52Z

schema/draft/schema.ts


 /**
- * Describes the name and version of an MCP implementation.
+ * Base interface for metadata with name and title (display name) properties.


should we hint that name is an identifier?

Suggested change

* Base interface for metadata with name and title (display name) properties.

* Base interface for metadata with name (identifier) and title (display name) properties.

bhosmer-ant · 2025-06-12T15:03:05Z

do we also need to update PromptReference?

yes! thanks for catching

ihrpr

LGTM

…l#663 Signed-off-by: luyunkui <luyunkui@58.com>

Follow-up to #109. The introduction of `title` in #109 is still a draft and is not supported in the latest specification, `Version 2025-06-18 (latest)`. In this PR, the README.md will be updated to mention this point and restore the references to the removed `annotations.title`. This aims to inform users that, as of `Version 2025-06-18 (latest)`, the use of `annotations.title` is considered stable. Additionally, separate validation for these parameters could be added. Please refer to the following comment regarding `annotations.title` and `title`: modelcontextprotocol/modelcontextprotocol#663 (comment)

Follow-up to #109. `title` has also been added to `serverInfo` and `clientInfo` by modelcontextprotocol/modelcontextprotocol#663. Since `clientInfo` is not treated as product code, support is implemented only in `serverInfo`. See also https://modelcontextprotocol.io/specification/2025-06-18/schema#implementation.

Commit 1c54a77 (PR #663) incorrectly added 'name' and 'title' fields to ResourceContents examples in the documentation. According to the schema, these fields only exist on Resource objects (used in resources/list), not on ResourceContents (TextResourceContents/BlobResourceContents) which are used in: - resources/read responses - embedded resources in prompts and tools - resource update notifications This commit removes the incorrectly documented fields to match the actual schema definition where ResourceContents only contains: - uri (required) - mimeType (optional) - text or blob field depending on content type

) Commit 1c54a77 (PR #663) incorrectly added 'name' and 'title' fields to ResourceContents examples in the documentation. According to the schema, these fields only exist on Resource objects (used in resources/list), not on ResourceContents (TextResourceContents/BlobResourceContents) which are used in: - resources/read responses - embedded resources in prompts and tools - resource update notifications This commit removes the incorrectly documented fields to match the actual schema definition where ResourceContents only contains: - uri (required) - mimeType (optional) - text or blob field depending on content type

Signed-off-by: luyunkui <luyunkui@58.com> Co-authored-by: Cliff Hall <cliff@futurescale.com> Co-authored-by: David Soria Parra <167242713+dsp-ant@users.noreply.github.com>

ZachGerman mentioned this pull request Jun 6, 2025

spec should define a unique ID for resource templates #566

Open

ZachGerman force-pushed the feature/displayName branch from d7801b2 to 7340d98 Compare June 6, 2025 20:34

dsp-ant added this to Standards Track Jun 9, 2025

dsp-ant moved this to Consulting in Standards Track Jun 9, 2025

dsp-ant added this to the DRAFT 2025-06-XX milestone Jun 9, 2025

dsp-ant reviewed Jun 10, 2025

View reviewed changes

schema/draft/schema.ts Show resolved Hide resolved

dsp-ant moved this from Consulting to In Review in Standards Track Jun 10, 2025

connor4312 reviewed Jun 10, 2025

View reviewed changes

ZachGerman force-pushed the feature/displayName branch 2 times, most recently from 6b634a1 to f00ada8 Compare June 11, 2025 21:29

Encourage title properties/usage for objects/resources likely to be r…

1c54a77

…epresented in a UI

ZachGerman force-pushed the feature/displayName branch from f00ada8 to 1c54a77 Compare June 11, 2025 21:36

ZachGerman changed the title ~~Encourage displayName properties/usage for objects/resources likely t…~~ Encourage title properties/usage for objects/resources likely t… Jun 11, 2025

Merge branch 'main' into feature/displayName

9d1374a

ZachGerman and others added 2 commits June 11, 2025 15:48

Merge branch 'modelcontextprotocol:main' into feature/displayName

bdcb021

Minor wording change

5bf5457

bhosmer-ant added 2 commits June 11, 2025 22:05

revert Root

9a96c28

Merge branch 'main' into feature/displayName

ffd8e6c

bhosmer-ant enabled auto-merge June 12, 2025 02:07

bhosmer-ant self-requested a review June 12, 2025 02:16

bhosmer-ant previously approved these changes Jun 12, 2025

View reviewed changes

ihrpr reviewed Jun 12, 2025

View reviewed changes

bhosmer-ant requested a review from ihrpr June 12, 2025 22:14

ihrpr approved these changes Jun 13, 2025

View reviewed changes

bhosmer-ant merged commit 8719898 into modelcontextprotocol:main Jun 13, 2025

github-project-automation bot moved this from In Review to Approved in Standards Track Jun 13, 2025

ihrpr mentioned this pull request Jun 13, 2025

Encourage title properties/usage for objects/resources likely #731

Open

felixweinberger mentioned this pull request Jun 17, 2025

Add title to tools, resources, prompts modelcontextprotocol/python-sdk#972

Merged

9 tasks

ihrpr mentioned this pull request Jun 17, 2025

changelog additions #768

Merged

primeinc mentioned this pull request Jun 18, 2025

Migrate from fastmcp to official modelcontextprotocol/python-sdk primeinc/telnyx-mcp-server#13

Draft

wommel0 mentioned this pull request Jun 19, 2025

Add title field for human-friendly display names, so that name can be used as a programmatic identifier abap-ai/mcp#50

Closed

connor4312 mentioned this pull request Jun 20, 2025

fix: deduplicate title definition in tools #813

Open

9 tasks

Mookse mentioned this pull request Jun 25, 2025

MCP: Upgrade to 2025-06-18 MyLife-Services/mylife-maht#536

Closed

6 tasks

YunKuiLu added a commit to YunKuiLu/modelcontextprotocol that referenced this pull request Jun 28, 2025

Update the concepts docs with the changes from PR modelcontextprotoco…

48f50ac

…l#663 Signed-off-by: luyunkui <luyunkui@58.com>

This was referenced Jun 28, 2025

Update the concepts docs with the changes from PR #663 #869

Merged

feat: Added optional title field to resource, tool, prompt modelcontextprotocol/java-sdk#349

Closed

jlowin mentioned this pull request Jun 28, 2025

Add title field support to FastMCP components jlowin/fastmcp#982

Merged

jonathanhefner mentioned this pull request Jul 11, 2025

Server concepts in learn #903

Merged

This was referenced Jul 19, 2025

[MCP 2025-06-18] Add title fields for human friendly display names indragiek/Context#52

Open

[MCP 2025-06-18] Remove support for sending batches indragiek/Context#53

Closed

tzolov mentioned this pull request Jul 22, 2025

Release 0.11.0 modelcontextprotocol/java-sdk#386

Closed

jdnvn mentioned this pull request Aug 18, 2025

Add title to tools, prompts and resources modelcontextprotocol/ruby-sdk#109

Merged

9 tasks

koic mentioned this pull request Aug 22, 2025

Document title as Draft and restore annotations.title modelcontextprotocol/ruby-sdk#113

Merged

9 tasks

koic mentioned this pull request Aug 28, 2025

Add title to serverInfo modelcontextprotocol/ruby-sdk#119

Merged

9 tasks

dsp-ant mentioned this pull request Sep 19, 2025

Fix incorrect name/title fields in ResourceContents documentation #1500

Merged

lvluoyue mentioned this pull request Oct 27, 2025

[Schema] _meta field for Ressource modelcontextprotocol/php-sdk#121

Closed

ajevans99 mentioned this pull request Oct 28, 2025

Support 2025-06-18 Spec modelcontextprotocol/swift-sdk#167

Open

9 tasks

	* Base interface for metadata with name and title (display name) properties.
	* Base interface for metadata with name (identifier) and title (display name) properties.

Encourage title properties/usage for objects/resources likely t… #663

Encourage title properties/usage for objects/resources likely t… #663

Uh oh!

Conversation

ZachGerman commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Breaking Changes

Types of changes

Checklist

To be added to docs if/when this PR is published to an official spec version:

Naming conventions:

Uh oh!

bhosmer-ant commented Jun 10, 2025

Uh oh!

Uh oh!

connor4312 left a comment

Choose a reason for hiding this comment

Uh oh!

connor4312 Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant commented Jun 11, 2025

Uh oh!

ZachGerman commented Jun 11, 2025

Uh oh!

bhosmer-ant commented Jun 11, 2025

Uh oh!

bhosmer-ant commented Jun 11, 2025

Uh oh!

ZachGerman commented Jun 11, 2025

Uh oh!

bhosmer-ant commented Jun 12, 2025

Uh oh!

bhosmer-ant left a comment

Choose a reason for hiding this comment

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

ihrpr Jun 12, 2025

Choose a reason for hiding this comment

Uh oh!

bhosmer-ant commented Jun 12, 2025

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ZachGerman commented Jun 6, 2025 •

edited

Loading

connor4312 Jun 10, 2025 •

edited

Loading