JBRes-7677: opentelementry support for MCP #1421

vova-jb · 2026-01-27T10:58:47Z

Motivation and Context

Mcp support for opentelemetry metrics

Breaking Changes

none

Type of the changes

[* ] New feature (non-breaking change which adds functionality)

vova-jb · 2026-01-27T14:18:55Z

tiginamaria

Thank you! Looks good to me, but I need @sdubov's second independent opinion here

tiginamaria · 2026-01-28T15:05:03Z

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/Tool.kt

    public val argsSerializer: KSerializer<TArgs>,
    public val resultSerializer: KSerializer<TResult>,
    public val descriptor: ToolDescriptor,
+    private val meta: Map<KClass<*>, Any> = emptyMap(),


For me it's fine like that (better then string or storage key), but need @sdubov oppinion here

Also not sure how it will work with java api

I have couple notes here:

I would name it metaInfo to match the naming with Message class that we use.

I'm not sure how this approach should be extended if we would like to pass this meta info through network. I would assume that this should be serrializable class. Otherwise, this data is only for for internal usage.

How would that work with Java API?

What is the problem with key-value approach here?

For key-value you mean string-string? It bas another option, but It's not type-safe and if I want MCP+ACP tool (for example) and it could cause key clashing. On the other hand it's easy to serialize and it's for sure java-friendly

tiginamaria · 2026-01-28T15:05:53Z

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/ToolRegistry.kt


        /**
         * A constant representing an empty registry with no tools.
+         * TODO: ToolRegistry is mutable but stored as an immutable object.


Maybe put deprecation with empty() replacement?

tiginamaria · 2026-01-28T15:09:23Z

...agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/tool/McpToolSupport.kt

+ * @property sessionId Unique identifier for the current MCP session, if session management is enabled.
+ */
+@InternalAgentsApi
+public class McpServerMeta(


For @sdubov: this was added to the core intentionally, as we don't wnat Otel dependend on MCP

Folks, as I see the metadata is used not for features, but for tool registry. I have a proposal to discuss here: What do you think if we add a general metadata key-value property (not directly referring MCP parameters) for our internal tools in the core module. MCP adds special MCP-related attributes to this metadata. We add this metadata to tool events, OTel will read this metadata and add necessary attributes to spans converting all or filtered MCP data into spans. WDYT?

sdubov

@vova-jb, thank you for your implementation. I looked through general approach and through details. Please see my comments in review. I would like to discuss two general questions that was raised in my mind:

How do we compose / wrap spans for MCP vs regular tool call spans?
How do we present meta information for tools?

I would also add someone from the team to discuss this together if you do not mind.

sdubov · 2026-01-29T12:29:31Z

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/AIAgent.kt

            agentConfig: AIAgentConfig,
            strategy: AIAgentGraphStrategy<Input, Output>,
-            toolRegistry: ToolRegistry = ToolRegistry.EMPTY,
+            toolRegistry: ToolRegistry = ToolRegistry.empty(),


@vova-jb, good point. I think it worth creating a separate ticket and separate update though

sdubov · 2026-01-29T12:33:41Z

...agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/tool/McpToolSupport.kt

+ * @property sessionId Unique identifier for the current MCP session, if session management is enabled.
+ */
+@InternalAgentsApi
+public class McpServerMeta(


Folks, as I see the metadata is used not for features, but for tool registry. I have a proposal to discuss here: What do you think if we add a general metadata key-value property (not directly referring MCP parameters) for our internal tools in the core module. MCP adds special MCP-related attributes to this metadata. We add this metadata to tool events, OTel will read this metadata and add necessary attributes to spans converting all or filtered MCP data into spans. WDYT?

sdubov · 2026-01-29T12:36:24Z

...agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/tool/McpToolSupport.kt

+    public val instructions: String?,
+    public val mcpProtocolVersion: String,
+    public val mcpTransportType: McpTransportType,
+    public val sessionId: String?,


We have session Id inside the framework. Maybe name it mcpSessionId to not mess with Koog session id?

sdubov · 2026-01-29T12:38:07Z

...agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/tool/McpToolSupport.kt

+public class McpServerMeta(
+    public val serverUrl: String?,
+    public val serverPort: Int?,
+    public val siteUrl: String?,


Sorry, could you please clarify the difference between serverUrl and siteUrl? I've read the properties KDoc, but I feel that I not exactly got it.

sdubov · 2026-01-29T12:39:25Z

...agents-core/src/commonMain/kotlin/ai/koog/agents/core/feature/handler/tool/McpToolSupport.kt

+     * This transport is typically used for local MCP servers running as separate
+     * processes that communicate via stdio. Suitable for development and local tools.
+     */
+    Pipe("pipe"),


@vova-jb, is not it called "stdio" mcp transport type by MCP providers?

sdubov · 2026-01-29T15:08:32Z

agents/agents-mcp-server/src/jvmTest/kotlin/ai/koog/agents/mcp/server/KoogToolAsMcpToolTest.kt

 import kotlin.test.assertTrue
 import kotlin.time.Duration.Companion.seconds

+@InternalAgentsApi


Could you please clarify why did you mark a test class as InternalAgentToolsApi. This annotation is used for internal methods that we explicitly mark for a users to show that it is not a public API.

sdubov · 2026-01-29T15:10:58Z

agents/agents-mcp/src/jvmTest/kotlin/ai/koog/agents/mcp/McpToolTest.kt

 import kotlin.time.Duration.Companion.seconds

 @Execution(ExecutionMode.SAME_THREAD)
+@InternalAgentsApi


Same comment as above for tests.

sdubov · 2026-01-29T15:28:22Z

agents/agents-tools/src/commonMain/kotlin/ai/koog/agents/core/tools/Tool.kt

    public val argsSerializer: KSerializer<TArgs>,
    public val resultSerializer: KSerializer<TResult>,
    public val descriptor: ToolDescriptor,
+    private val meta: Map<KClass<*>, Any> = emptyMap(),


I have couple notes here:

I would name it metaInfo to match the naming with Message class that we use.

I'm not sure how this approach should be extended if we would like to pass this meta info through network. I would assume that this should be serrializable class. Otherwise, this data is only for for internal usage.

How would that work with Java API?

What is the problem with key-value approach here?

sdubov · 2026-01-29T15:33:12Z

examples/simple-examples/src/main/kotlin/ai/koog/agents/example/features/langfuse/Langfuse.kt

 *  1. Set up a Langfuse project and credentials as described [here](https://langfuse.com/docs/get-started#create-new-project-in-langfuse)
 *  2. Get Langfuse credentials as described [here](https://langfuse.com/faq/all/where-are-langfuse-api-keys)
 *  3. Set `LANGFUSE_HOST`, `LANGFUSE_PUBLIC_KEY`, and `LANGFUSE_SECRET_KEY` environment variables
+ *  4. Set `OPENAI_API_KEY` from [here](https://platform.openai.com/account/api-keys)


Changes in this file seem unrelated to the code from the PR. Maybe we can do it separately if needed?

sdubov · 2026-01-29T15:40:15Z

examples/simple-examples/env.template.properties

+#
+LANGFUSE_SECRET_KEY=sk-lf-...
+LANGFUSE_PUBLIC_KEY=pk-lf-...
+LANGFUSE_HOST=http://localhost:3000


Could you please skip the value part as it is defined for other env vars to keep it consistent?

vova-jb force-pushed the vm/otel-mcp-3 branch from b8a8889 to 4eea75b Compare January 27, 2026 11:34

vova-jb force-pushed the vm/otel-mcp-3 branch 3 times, most recently from 1d40250 to 1633b4a Compare January 28, 2026 10:55

vova-jb requested a review from tiginamaria January 28, 2026 10:56

vova-jb marked this pull request as ready for review January 28, 2026 10:56

vova-jb force-pushed the vm/otel-mcp-3 branch 2 times, most recently from cdddf62 to 32ca582 Compare January 28, 2026 12:13

tiginamaria reviewed Jan 28, 2026

View reviewed changes

tiginamaria requested a review from sdubov January 28, 2026 15:11

sdubov reviewed Jan 29, 2026

View reviewed changes

vova-jb added 4 commits January 29, 2026 16:56

JBRes-7677: opentelementry support for MCP

7feadac

JBRes-7677: langfuse example for mcp metrics in opentelemetry

d7e8693

fixup! JBRes-7677: opentelementry support for MCP

04dec00

fixup! JBRes-7677: opentelementry support for MCP

f16df01

vova-jb force-pushed the vm/otel-mcp-3 branch from 32ca582 to f16df01 Compare January 29, 2026 16:30

fixup! JBRes-7677: langfuse example for mcp metrics in opentelemetry

55171d6

sdubov requested review from EugeneTheDev and sdubov January 29, 2026 20:16

fixup! JBRes-7677: opentelementry support for MCP

6efa083

JBRes-7677: opentelementry support for MCP #1421

Are you sure you want to change the base?

JBRes-7677: opentelementry support for MCP #1421

Uh oh!

Conversation

vova-jb commented Jan 27, 2026

Motivation and Context

Breaking Changes

Type of the changes

Uh oh!

vova-jb commented Jan 27, 2026

Uh oh!

tiginamaria left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sdubov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants