[MCP Servers] non-reference documentation - #8500
Conversation
|
Please note that this is a new documentation referred to a new section, called MCP Servers. |
| [[stateless-mode]] | ||
| === Stateless mode | ||
|
|
||
| NOTE: In stateless mode, features that rely on per-client session state — including cancellation — are not available. Each request is handled independently with no shared state between calls. | ||
|
|
||
| By default, `mcp-1.0` maintains sessions to associate requests from the same client. In horizontally scaled or clustered deployments where requests can be routed to different server instances, enable stateless mode to remove this session affinity: | ||
|
|
||
| [source,xml] | ||
| ---- | ||
| <application location="myMcpApp.war"> | ||
| <mcpServer stateless="true"/> | ||
| </application> | ||
| ---- | ||
|
|
||
| In stateless mode, each incoming request is processed independently. This makes the server suitable for load-balanced environments where there is no sticky session routing, but the trade-off is that client-driven cancellation of in-flight tool calls is not supported. |
There was a problem hiding this comment.
We probably need to start this section by saying that MCP is a stateful protocol (up to version 2025-11-25) and that requests from the same MCP session must be handled by the same server. In a clustered environment, this requires a load balancer that can route requests based on the Mcp-Session-Id header.
To allow easier deployment in a cluster, it's possible to disable stateful features so that special routing rules are not required.
The trade-off is that client-driven cancellation of in-flight tool calls is not supported.
((explain config))
There was a problem hiding this comment.
Section has been updated
| ==== Server description and metadata | ||
|
|
||
| During MCP initialisation, the server sends a `serverInfo` block containing the server name, version, and description. Configure it with the nested `<info>` element: |
There was a problem hiding this comment.
We should highlight that some AI applications may display this information to the user, since that explains why it's important to set it.
|
We should include something about which versions of the MCP protocol we support ( Some of this information could possibly go on the feature reference doc page. |
| === Test with the MCP Inspector | ||
|
|
||
| The https://github.com/modelcontextprotocol/inspector[MCP Inspector] is an open-source browser UI that lets you browse and invoke tools on any MCP server. It is the easiest way to verify your tools are registered correctly before connecting a full AI agent. With `npm` installed, run: | ||
|
|
||
| [source,sh] | ||
| ---- | ||
| npx @modelcontextprotocol/inspector | ||
| ---- |
There was a problem hiding this comment.
This looks like we're asking users to test the server before they've added a tool to it.
There was a problem hiding this comment.
Rephrased to make more sense.
| === Using structured content | ||
|
|
||
| NOTE: Structured content is only returned to clients that negotiate MCP protocol version `2025-06-18` or later. Clients using earlier protocol versions receive the unstructured text content only. | ||
|
|
||
| When `structuredContent = true` on `@Tool`, Liberty serialises the return value as JSON and includes it in the `structuredContent` field of the tool response alongside the unstructured text representation. This allows clients to consume a strongly-typed object rather than parsing text. | ||
|
|
||
| The following example returns a `City` record as both unstructured text (the default JSON serialisation) and as structured JSON content: |
There was a problem hiding this comment.
I think we need a bit more of an explanation of stuctured vs. unstructured data in MCP and that unstructured is the default because AI deals well with unstructured data.
We can also mention that when returning structured data, the json representation is also returned as unstructured text for backwards compatibility.
|
We also need documentation on securing access to MCP servers, including how to set up the |
| To allow easier deployment in a cluster, it's possible to disable stateful features so that special routing rules are not required. | ||
| The trade-off is that client-driven cancellation of in-flight tool calls is not supported. | ||
|
|
||
| NOTE: In stateless mode, features that rely on per-client session state — including cancellation — are not available. Each request is handled independently with no shared state between calls. |
|
Please do not merge the PR - I have moved the contents of this PR separately into draft. Once the Draft site is up - I will share the Draft link in issue. Regards, |
4 participants
Resolves #8493