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 2939613b [doc] Create a dedicated section for introducing MCP. (#453)
2939613b is described below
commit 2939613b68404be52fe0a3b7bae54da64cf0eafc
Author: Wenjin Xie <[email protected]>
AuthorDate: Tue Jan 20 09:31:07 2026 +0800
[doc] Create a dedicated section for introducing MCP. (#453)
---
docs/content/docs/development/mcp.md | 190 ++++++++++++++++++++++++++++++
docs/content/docs/development/prompts.md | 152 +-----------------------
docs/content/docs/development/tool_use.md | 153 +-----------------------
3 files changed, 193 insertions(+), 302 deletions(-)
diff --git a/docs/content/docs/development/mcp.md
b/docs/content/docs/development/mcp.md
new file mode 100644
index 00000000..c6e97d6b
--- /dev/null
+++ b/docs/content/docs/development/mcp.md
@@ -0,0 +1,190 @@
+---
+title: MCP
+weight: 7
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## Overview
+
+MCP (Model Context Protocol) is a standardized protocol for integrating AI
applications with external data sources and tools. Flink Agents provides the
support for using prompts and tools from MCP server.
+
+{{< hint warning >}}
+**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 >}}
+
+## Declare MCP Server in Agent
+
+Developer can declare a mcp server by decorator/annotation when creating an
Agent.
+
+{{< tabs "Use MCP Tools in Agent" >}}
+
+{{< tab "Python" >}}
+```python
+class ReviewAnalysisAgent(Agent):
+
+ @mcp_server
+ @staticmethod
+ def my_mcp_server() -> ResourceDescriptor:
+ """Define MCP server connection."""
+ return ResourceDescriptor(clazz=Constant.MCP_SERVER,
+ endpoint="http://127.0.0.1:8000/mcp";)
+```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```java
+public class ReviewAnalysisAgent extends Agent {
+
+ @MCPServer
+ public static ResourceDescriptor myMcp() {
+ return ResourceDescriptor.Builder.newBuilder(Constant.MCP_SERVER)
+ .addInitialArgument("endpoint", MCP_ENDPOINT)
+ .addInitialArgument("timeout", 30)
+ .build();
+ }
+}
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
+**Key points:**
+- Use decorator/annotation to define MCP server connection
+ - In Python, use `@mcp_server`.
+ - In Java, use `@MCPServer`.
+- Use the builder pattern in Java to configure the MCP server with endpoint,
timeout, headers, and authentication
+
+### Authentication
+
+MCP servers can be configured with authentication:
+
+{{< tabs "MCP Server Authentication" >}}
+
+{{< tab "Python" >}}
+```python
+@mcp_server
+@staticmethod
+def authenticated_mcp_server() -> MCPServer:
+ """Connect to MCP server with authentication."""
+ return ResourceDescriptor(clazz=Constant.MCP_SERVER,
+ 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 ResourceDescriptor.Builder.newBuilder(Constant.MCP_SERVER)
+ .addInitialArgument("endpoint",
"http://api.example.com/mcp";)
+ .addInitialArgument("timeout", 30)
+ .addInitialArgument("auth", new
BearerTokenAuth("your-oauth-token"))
+ .build();
+
+ // Or using Basic Authentication
+ // .addInitialArgument("auth", new BasicAuth("username", "password"))
+
+ // Or using API Key Authentication
+ // .addInitialArgument("auth", new ApiKeyAuth("X-API-Key", "your-api-key"))
+}
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
+**Authentication options:**
+- `BearerTokenAuth` - For OAuth 2.0 and JWT tokens
+- `BasicAuth` - For username/password authentication
+- `ApiKeyAuth` - For API key authentication via custom headers
+
+## Use MCP prompts and tools in Agent
+
+
+MCP prompts and tools are managed by external MCP servers and automatically
discovered when you define an MCP server connection in your agent.
+
+{{< tabs "Use MCP Prompts and Tools in Agent" >}}
+
+{{< tab "Python" >}}
+```python
+class ReviewAnalysisAgent(Agent):
+
+ @mcp_server
+ @staticmethod
+ def review_mcp_server() -> ResourceDescriptor:
+ """Connect to MCP server."""
+ return ResourceDescriptor(clazz=Constant.MCP_SERVER,
+ endpoint="http://127.0.0.1:8000/mcp";)
+
+ @chat_model_setup
+ @staticmethod
+ def review_model() -> ResourceDescriptor:
+ return ResourceDescriptor(
+ clazz=OllamaChatModelSetup,
+ connection="ollama_server",
+ model="qwen3:8b",
+ # Reference MCP prompt by name like local prompt
+ prompt="review_analysis_prompt",
+ # Reference MCP tool by name like function tool
+ tools=["notify_shipping_manager"],
+ )
+```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```java
+public class ReviewAnalysisAgent extends Agent {
+
+ @MCPServer
+ public static ResourceDescriptor myMcp() {
+ return ResourceDescriptor.Builder.newBuilder(Constant.MCP_SERVER)
+ .addInitialArgument("endpoint",
"http://127.0.0.1:8000/mcp";)
+ .addInitialArgument("timeout", 30)
+ .build();
+ }
+
+ @ChatModelSetup
+ public static ResourceDescriptor reviewModel() {
+ return
ResourceDescriptor.Builder.newBuilder(OllamaChatModelSetup.class.getName())
+ .addInitialArgument("connection", "ollamaChatModelConnection")
+ .addInitialArgument("model", "qwen3:8b")
+ // Reference MCP prompt by name like local prompt
+ .addInitialArgument("prompt", "review_analysis_prompt")
+ // Reference MCP tool by name like function tool
+ .addInitialArgument("tools",
Collections.singletonList("notifyShippingManager"))
+ .build();
+ }
+}
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
+**Key points:**
+- All tools and prompts from the MCP server are automatically registered.
+- Reference MCP prompts and tools by their names, like reference [local
prompt]({{< ref "docs/development/prompts/#using-prompts-in-agents" >}}) and
[function tool]({{< ref
"docs/development/tool_use/#define-tool-as-static-method-in-agent-class" >}}) .
\ No newline at end of file
diff --git a/docs/content/docs/development/prompts.md
b/docs/content/docs/development/prompts.md
index 0526b5dc..0d8fae3f 100644
--- a/docs/content/docs/development/prompts.md
+++ b/docs/content/docs/development/prompts.md
@@ -40,9 +40,7 @@ Local prompts are templates defined directly in your code.
They support variable
MCP (Model Context Protocol) prompts are managed by external MCP servers. They
enable dynamic prompt retrieval, centralized prompt management, and integration
with external prompt repositories.
-{{< hint warning >}}
-MCP Prompt is only supported in python currently.
-{{< /hint >}}
+See [MCP]({{< ref "docs/development/mcp" >}}) for details.
## Local Prompt
### Creating from Text
@@ -327,150 +325,4 @@ public class ReviewAnalysisAgent extends Agent {
{{< /tabs >}}
-Prompts use `{variable_name}` syntax for template variables. Variables are
filled from `ChatMessage.extra_args`. The prompt is automatically applied when
the chat model is invoked.
-
-## MCP Prompt
-
-{{< hint info >}}
-MCP (Model Context Protocol) is a standardized protocol for integrating AI
applications with external data sources and tools. MCP prompts allow dynamic
prompt retrieval from MCP servers.
-{{< /hint >}}
-
-{{< hint warning >}}
-**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.
-
-### Define MCP Server with Prompts
-
-Create an MCP server that exposes prompts using the `FastMCP` library:
-
-```python
-# mcp_server.py
-mcp = FastMCP("ReviewServer")
-
[email protected]()
-def review_analysis_prompt(product_id: str, review: str) -> str:
- """Prompt for analyzing product reviews."""
- return f"""
- Analyze the following product review and provide a satisfaction score
(1-5).
-
- Product ID: {product_id}
- Review: {review}
-
- Output format: {{"score": 1-5, "reasons": ["reason1", "reason2"]}}
- """
-
-mcp.run("streamable-http")
-```
-
-**Key points:**
-- Use `@mcp.prompt()` decorator to define prompts
-- Prompt function parameters become template variables
-- The function name becomes the prompt identifier
-
-### Use MCP Prompts in Agent
-
-Connect to the MCP server and use its prompts in your agent:
-
-{{< tabs "Use MCP Prompts in Agent" >}}
-
-{{< tab "Python" >}}
-```python
-class ReviewAnalysisAgent(Agent):
-
- @mcp_server
- @staticmethod
- def review_mcp_server() -> MCPServer:
- """Connect to MCP server."""
- return MCPServer(endpoint="http://127.0.0.1:8000/mcp";)
-
- @chat_model_connection
- @staticmethod
- def ollama_server() -> ResourceDescriptor:
- """Ollama connection."""
- return ResourceDescriptor(clazz=OllamaChatModelConnection)
-
- @chat_model_setup
- @staticmethod
- def review_model() -> ResourceDescriptor:
- return ResourceDescriptor(
- clazz=OllamaChatModelSetup,
- connection="ollama_server",
- model="qwen3:8b",
- prompt="review_analysis_prompt", # Reference MCP prompt by name
- )
-
- @action(InputEvent)
- @staticmethod
- def process_input(event: InputEvent, ctx: RunnerContext) -> None:
- input_data = event.input
-
- # Provide prompt variables via extra_args
- msg = ChatMessage(
- role=MessageRole.USER,
- extra_args={
- "product_id": input_data.product_id,
- "review": input_data.review
- }
- )
- 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:**
-- 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
+Prompts use `{variable_name}` syntax for template variables. Variables are
filled from `ChatMessage.extra_args`. The prompt is automatically applied when
the chat model is invoked.
\ 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 74d8a6e4..99e23cf2 100644
--- a/docs/content/docs/development/tool_use.md
+++ b/docs/content/docs/development/tool_use.md
@@ -181,155 +181,4 @@ ReActAgent reviewAnalysisReactAgent = new ReActAgent(
## MCP Tool
-{{< hint info >}}
-MCP (Model Context Protocol) is a standardized protocol for integrating AI
applications with external data sources and tools. MCP tools allow dynamic tool
retrieval from MCP servers.
-{{< /hint >}}
-
-{{< hint warning >}}
-**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 tools are managed by external MCP servers and automatically discovered
when you define an MCP server connection in your agent.
-
-### Define MCP Server with Tools
-
-Create an MCP server that exposes tools using the `FastMCP` library:
-
-```python
-# mcp_server.py
-mcp = FastMCP("ReviewServer")
-
[email protected]()
-async def notify_shipping_manager(id: str, review: str) -> None:
- """Notify the shipping manager when product received a negative review due
to
- shipping damage.
-
- Parameters
- ----------
- id : str
- The id of the product that received a negative review due to shipping
damage
- review: str
- The negative review content
- """
- ...
-
-mcp.run("streamable-http")
-```
-
-**Key points:**
-- Use `@mcp.tool()` decorator to define tools
-- The function name becomes the tool identifier
-
-### Use MCP Tools in Agent
-
-Connect to the MCP server and use its tools in your agent:
-
-{{< tabs "Use MCP Tools in Agent" >}}
-
-{{< tab "Python" >}}
-```python
-class ReviewAnalysisAgent(Agent):
- ...
-
- @mcp_server
- @staticmethod
- def review_mcp_server() -> MCPServer:
- """Connect to MCP server."""
- return MCPServer(endpoint="http://127.0.0.1:8000/mcp";)
-
- @chat_model_setup
- @staticmethod
- def review_model() -> ResourceDescriptor:
- return ResourceDescriptor(
- clazz=OllamaChatModelSetup,
- connection="ollama_server",
- model="qwen3:8b",
- 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:**
-- 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
+See [MCP]({{< ref "docs/development/mcp" >}}) for details.
