[Bug] Flink Agents Java MCPServer#listPrompts crashes(NullPointer) when required field is missing in prompt arguments

[Vino1016]

Search before asking

• I searched in the issues and found nothing similar.

Description

Flink Agents Java MCP client crashes when deserializing prompt arguments if the required field is omitted by the MCP server.

According to the MCP specification, PromptArgument.required is optional (required?: boolean). MCP servers may omit it, in which case Jackson deserializes it as null.

In org.apache.flink.agents.integrations.mcp.MCPServer#listPrompts, Flink Agents unconditionally passes arg.required() to new MCPPrompt.PromptArgument(...). Later Boolean unboxing triggers a NullPointerException:
argumentsMap.put(arg.name(), new MCPPrompt.PromptArgument(arg.name(), arg.description(), arg.required()));

Impact: Any Java agent connecting to a standard MCP server that omits required (or is null) will fail to list prompts, crashing agent initialization. Tools-only MCP servers or any server returning optional arguments without required are affected.

Steps to Reproduce

Create a Java agent with @MCPSERVER pointing to an MCP server that returns prompts where required is omitted or null.

Run the agent.

Observe a NullPointerException during MCPServer#listPrompts.

Caused by: java.lang.NullPointerException: Cannot invoke "java.lang.Boolean.booleanValue()" because the return value of "io.modelcontextprotocol.spec.McpSchema$PromptArgument.required()" is null
at org.apache.flink.agents.integrations.mcp.MCPServer.listPrompts(MCPServer.java:354)
at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)

How to reproduce

Create a Java agent with @MCPSERVER pointing to an MCP server that returns prompts where required is omitted or null.

Run the agent.

Observe a NullPointerException during MCPServer#listPrompts.

Expected behavior
The agent should treat null required values as false (optional), matching the MCP spec. Agent initialization should succeed, and prompts should be registered correctly.

Version and environment

Flink Agents: 0.2.0

Flink: 2.0.0

Java: 21

OS: macOS (also reproducible on Linux CI)

Are you willing to submit a PR?

• I'm willing to submit a PR!

[wenjin272]

Hi, @Vino1016, thank you for reporting this bug.

I see this bug is caused by the arg.required() returns null. I think we can validate it before pass it to the constructor of MCPPrompt.PromptArgument, like

argumentsMap.put(
        arg.name(),
        new MCPPrompt.PromptArgument(
                arg.name(), arg.description(), arg.required() != null && arg.required()));

However, I have two questions I would like to ask：

According to the MCP specification, PromptArgument.required is optional (required?: boolean).

Could you please let me know where this information was obtained? I couldn't find it at https://modelcontextprotocol.io/specification/2025-11-25/server/prompts.

Tools-only MCP servers or any server returning optional arguments without required are affected.

Why tools-only MCP servers are also affected? If the prompts are empty, MCPPrompt.PromptArgument should not be constructed.
And in #538, before list the prompts, we add a check to verify whether the MCP Server supports prompts.

[Vino1016]

@wenjin272 Hi there,

Thanks for your quick response and the proposed fix! I agree that validating the required field before passing it to the constructor is the right approach, and treating null as false aligns perfectly with the expected behavior.

Regarding your first question:

The required field in PromptArgument is indeed optional in the MCP specification. Here are the sources:

1. MCP Concept Documentation: The official MCP documentation (https://modelcontextprotocol.info/zh-cn/docs/concepts/prompts/) explicitly defines the required field as required?: boolean, indicating it is an optional boolean.

2. MCP SDK Implementations: For example, the JetBrains Kotlin SDK ([https://jetbrains.github.io/mcp-kotlin-sdk/-m-c-p%20-kotlin%20-s-d-k/org.jetbrains.kotlinx.mcp/-prompt-argument/index.html](https://jetbrains.github.io/mcp-kotlin-sdk/-m-c-p -kotlin -s-d-k/org.jetbrains.kotlinx.mcp/-prompt-argument/index.html)) defines required as Boolean?, a nullable boolean, which enforces that the field can be omitted or null.

Regarding your second question:

You're right that if a server is truly "tools-only" and does not support prompts, the listPrompts method should not be called due to the check added in #538. However, in practice, some MCP servers (like the Kubernetes MCP server I was testing with) do support prompts and return a non-empty list of prompts, but some of the arguments in those prompts omit the required field.

As shown in the debug screenshot I provided:

• The MCP server returns a PromptArgument with name="namespace".
• The required field is explicitly null (not false).
• This causes the NPE during initialization, even though the server is not strictly "tools-only".

This scenario is not hypothetical; it's a real-world case I encountered. The fix you proposed will handle this correctly by treating null as false, allowing the agent to initialize successfully.

Thanks again for your help in addressing this issue!

[wenjin272]

Hi, @Vino1016. Thank you very much for your explanation, and it clearly addressed my questions. Thanks again!

Are you interested in fixing this issue? If so, I can assign this ticket to you; otherwise, I will fix it soon.

[Vino1016]

Hi, @wenjin272 I’d like to work on this issue and will submit a PR shortly.

[Vino1016]

@wenjin272 Hi, After thinking about this a bit more. I think the null check you proposed can indeed avoid the NPE temporarily. However, I think maybe it’s more of a workaround rather than a fundamental solution.

The root problem is that required in the MCP spec is an optional boolean field, which means it can be null or omitted. Using the primitive boolean in org.apache.flink.agents.integrations.mcp.MCPPrompt.PromptArgument cannot represent null values, which directly causes the exception during deserialization.

And I found the required field in the official MCP spec model io.modelcontextprotocol.spec.McpSchema.PromptArgument is explicitly defined as Boolean (nullable wrapper type), which aligns with the MCP spec that required is an optional field.

For a more robust fix, maybe we should change boolean to the wrapper type Boolean and set it to false by default when it is null.
If we keep using primitive boolean without fixing the type, similar null pointer exceptions may occur in other places where PromptArgument is constructed or used in the future.

[wenjin272]

For a more robust fix, maybe we should change boolean to the wrapper type Boolean and set it to false by default when it is null.

Make sense. Thanks for your proposal and I assigned this ticket to you.