This is an automated email from the ASF dual-hosted git repository.
xtsong pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
The following commit(s) were added to refs/heads/main by this push:
new bf5beb3 [doc] Add doc for JAVA MCP Server tools and prompts (#421)
bf5beb3 is described below
commit bf5beb3404526439164e12360e37440a1414bdd6
Author: Yash Anand <[email protected]>
AuthorDate: Thu Jan 8 17:32:54 2026 -0800
[doc] Add doc for JAVA MCP Server tools and prompts (#421)
---
docs/content/docs/development/prompts.md | 63 ++++++++++++++++++++--
docs/content/docs/development/tool_use.md | 90 +++++++++++++++++++++++++++++--
2 files changed, 146 insertions(+), 7 deletions(-)
diff --git a/docs/content/docs/development/prompts.md
b/docs/content/docs/development/prompts.md
index 591fabf..0526b5d 100644
--- a/docs/content/docs/development/prompts.md
+++ b/docs/content/docs/development/prompts.md
@@ -336,7 +336,7 @@ MCP (Model Context Protocol) is a standardized protocol for
integrating AI appli
{{< /hint >}}
{{< hint warning >}}
-MCP Prompt is only supported in python currently.
+**JDK Requirement (Java API only):** If you are using the **Java API** to
develop Flink Agents jobs with MCP, you need **JDK 17 or higher**. This
requirement does not apply to **Python API** users - the Python SDK has its own
MCP implementation and works with JDK 11+.
{{< /hint >}}
MCP prompts are managed by external MCP servers and automatically discovered
when you define an MCP server connection in your agent.
@@ -373,6 +373,9 @@ mcp.run("streamable-http")
Connect to the MCP server and use its prompts in your agent:
+{{< tabs "Use MCP Prompts in Agent" >}}
+
+{{< tab "Python" >}}
```python
class ReviewAnalysisAgent(Agent):
@@ -413,9 +416,61 @@ class ReviewAnalysisAgent(Agent):
)
ctx.send_event(ChatRequestEvent(model="review_model", messages=[msg]))
```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```java
+public class ReviewAnalysisAgent extends Agent {
+
+ @MCPServer
+ public static org.apache.flink.agents.integrations.mcp.MCPServer
reviewMcpServer() {
+ return org.apache.flink.agents.integrations.mcp.MCPServer
+ .builder("http://127.0.0.1:8000/mcp";)
+ .timeout(Duration.ofSeconds(30))
+ .build();
+ }
+
+ @ChatModelConnection
+ public static ResourceDescriptor ollamaServer() {
+ return
ResourceDescriptor.Builder.newBuilder(OllamaChatModelConnection.class.getName())
+ .build();
+ }
+
+ @ChatModelSetup
+ public static ResourceDescriptor reviewModel() {
+ return
ResourceDescriptor.Builder.newBuilder(OllamaChatModelSetup.class.getName())
+ .addInitialArgument("connection", "ollamaServer")
+ .addInitialArgument("model", "qwen3:8b")
+ .addInitialArgument("prompt", "reviewAnalysisPrompt") //
Reference MCP prompt by name
+ .build();
+ }
+
+ @Action(listenEvents = {InputEvent.class})
+ public static void processInput(InputEvent event, RunnerContext ctx)
throws Exception {
+ CustomTypesAndResources.ProductReview inputData =
+ (CustomTypesAndResources.ProductReview) event.getInput();
+
+ // Provide prompt variables via extra_args
+ ChatMessage msg = new ChatMessage(
+ MessageRole.USER,
+ "",
+ Map.of(
+ "product_id", inputData.getProductId(),
+ "review", inputData.getReview()
+ )
+ );
+ ctx.sendEvent(new ChatRequestEvent("reviewModel", List.of(msg)));
+ }
+}
+```
+{{< /tab >}}
+
+{{< /tabs >}}
**Key points:**
-- Use `@mcp_server` decorator to define MCP server connection
-- Reference MCP prompts by their function name (e.g.,
`"review_analysis_prompt"`)
-- Provide prompt parameters using `ChatMessage.extra_args`
+- In Python, use `@mcp_server` decorator to define MCP server connection
+- In Java, use `@MCPServer` annotation to define MCP server connection
+- Use the builder pattern in Java to configure the MCP server with endpoint,
timeout, headers, and authentication
+- Reference MCP prompts by their function name (e.g.,
`"review_analysis_prompt"` in Python, `"reviewAnalysisPrompt"` in Java)
+- Provide prompt parameters using `ChatMessage.extra_args` (Python) or the
third parameter of `ChatMessage` constructor (Java)
- All prompts and tools from the MCP server are automatically registered
\ No newline at end of file
diff --git a/docs/content/docs/development/tool_use.md
b/docs/content/docs/development/tool_use.md
index 5d8f994..74d8a6e 100644
--- a/docs/content/docs/development/tool_use.md
+++ b/docs/content/docs/development/tool_use.md
@@ -224,6 +224,9 @@ mcp.run("streamable-http")
Connect to the MCP server and use its tools in your agent:
+{{< tabs "Use MCP Tools in Agent" >}}
+
+{{< tab "Python" >}}
```python
class ReviewAnalysisAgent(Agent):
...
@@ -244,8 +247,89 @@ class ReviewAnalysisAgent(Agent):
tools=["notify_shipping_manager"], # Reference MCP tool by name
)
```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```java
+public class ReviewAnalysisAgent extends Agent {
+
+ @MCPServer
+ public static org.apache.flink.agents.integrations.mcp.MCPServer
reviewMcpServer() {
+ return org.apache.flink.agents.integrations.mcp.MCPServer
+ .builder("http://127.0.0.1:8000/mcp";)
+ .timeout(Duration.ofSeconds(30))
+ .build();
+ }
+
+ @ChatModelSetup
+ public static ResourceDescriptor reviewModel() {
+ return
ResourceDescriptor.Builder.newBuilder(OllamaChatModelSetup.class.getName())
+ .addInitialArgument("connection", "ollamaChatModelConnection")
+ .addInitialArgument("model", "qwen3:8b")
+ .addInitialArgument("tools",
Collections.singletonList("notifyShippingManager")) // Reference MCP tool by
name
+ .build();
+ }
+}
+```
+{{< /tab >}}
+
+{{< /tabs >}}
**Key points:**
-- Use `@mcp_server` decorator to define MCP server connection
-- Reference MCP tools by their function name (e.g.,
`"notify_shipping_manager"`)
-- All tools from the MCP server are automatically registered
\ No newline at end of file
+- In Python, use `@mcp_server` decorator to define MCP server connection
+- In Java, use `@MCPServer` annotation to define MCP server connection
+- Use the builder pattern in Java to configure the MCP server with endpoint,
timeout, headers, and authentication
+- Reference MCP tools by their function name (e.g.,
`"notify_shipping_manager"` in Python, `"notifyShippingManager"` in Java)
+- All tools from the MCP server are automatically registered
+
+### MCP Server Authentication
+
+MCP servers can be configured with authentication in both Python and Java:
+
+{{< tabs "MCP Server Authentication" >}}
+
+{{< tab "Python" >}}
+```python
+@mcp_server
+@staticmethod
+def authenticated_mcp_server() -> MCPServer:
+ """Connect to MCP server with authentication."""
+ return MCPServer(
+ endpoint="http://api.example.com/mcp";,
+ headers={"Authorization": "Bearer your-token"}
+ )
+ # Or using Basic Authentication
+ # credentials = base64.b64encode(b"username:password").decode("ascii")
+ # headers={"Authorization": f"Basic {credentials}"}
+
+ # Or using API Key Authentication
+ # headers={"X-API-Key": "your-api-key"}
+```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```java
+@MCPServer
+public static org.apache.flink.agents.integrations.mcp.MCPServer
authenticatedMcpServer() {
+ // Using Bearer Token Authentication
+ return org.apache.flink.agents.integrations.mcp.MCPServer
+ .builder("http://api.example.com/mcp";)
+ .auth(new BearerTokenAuth("your-oauth-token"))
+ .timeout(Duration.ofSeconds(30))
+ .build();
+
+ // Or using Basic Authentication
+ // .auth(new BasicAuth("username", "password"))
+
+ // Or using API Key Authentication
+ // .auth(new ApiKeyAuth("X-API-Key", "your-api-key"))
+}
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
+**Authentication options in Java:**
+- `BearerTokenAuth` - For OAuth 2.0 and JWT tokens
+- `BasicAuth` - For username/password authentication
+- `ApiKeyAuth` - For API key authentication via custom headers
\ No newline at end of file
