Skip to content

Connect: Koog

Recipe · through our MCP server · their docs checked 2026-11-17 · MCP route tested live

Koog (JetBrains, Kotlin) turns an MCP server into a ToolRegistry with McpToolRegistryProvider. Its streamableHttp { } helper sets no request headers; to send our bearer token, hand it the official Kotlin SDK's transport, which is what our tested Kotlin client uses.

Our side

def public_app(tools: Registry, host: str, agent_token: str, reviewer_token: str) -> Any:
    """REST at /, MCP at /mcp, one bearer check for both: for a host on the internet."""
    from mcp.server.transport_security import TransportSecuritySettings

    from agent_adapter.server import create_app

    tokens = {
        agent_token: Principal("hosted-agent"),  # the token the remote framework sends
        reviewer_token: Principal("reviewer@example.com", scopes=frozenset({APPROVER_SCOPE})),
    }
    security = TransportSecuritySettings(allowed_hosts=[host], allowed_origins=[f"https://{host}"])
    return create_app(
        tools,
        authenticate=bearer_auth(tokens),
        host="0.0.0.0",  # a public bind: the public-host checks apply
        allowed_hosts=[host],  # REST: any other Host header gets 421
        mcp_options={"transport_security": security},  # MCP: the same rule
    )


hosted = registry.subset(tags=["hosted"])  # no confirm tools: hosted runtimes cannot resume them

Serve public_app(hosted, …): Koog does not send our resume keys back. In development on one machine, local_app() is enough.

Their side

Add Koog (ai.koog:koog-agents), its MCP module (ai.koog:agents-mcp, a beta module: 1.3.0-beta for Koog 1.3.0) and a Ktor engine such as io.ktor:ktor-client-cio:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.mcp.McpToolRegistryProvider
import ai.koog.agents.mcp.metadata.McpServerInfo
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import io.ktor.client.HttpClient
import io.ktor.client.engine.cio.CIO
import io.ktor.client.plugins.sse.SSE
import io.ktor.client.request.header
import io.modelcontextprotocol.kotlin.sdk.client.StreamableHttpClientTransport

val http = HttpClient(CIO) { install(SSE) }
val transport = StreamableHttpClientTransport(http, "https://tools.example.com/mcp") {
    header("Authorization", "Bearer ${System.getenv("AA_AGENT_TOKEN")}")
}

val toolRegistry = McpToolRegistryProvider.fromTransport(
    transport = transport,
    serverInfo = McpServerInfo(url = "https://tools.example.com/mcp"),
    name = "shop-agent",
    version = "1.0.0",
)

val agent = AIAgent(
    promptExecutor = executor,
    llmModel = OpenAIModels.Chat.GPT4o,
    toolRegistry = toolRegistry,
)
Key Meaning
StreamableHttpClientTransport(http, url) { ... } the Kotlin SDK's Streamable HTTP transport; the block runs on every request
header("Authorization", ...) the bearer token
McpToolRegistryProvider.fromTransport(...) connects, lists our tools and wraps each as a Koog tool; serverInfo is required
McpToolRegistryProvider.fromClient(...) the same, from an MCP Client you already connected
AIAgent(toolRegistry = ...) offers the tools to the agent

defaultSseTransport(url) speaks the older SSE transport, which our server does not serve: use the Streamable HTTP transport above.

Checklist

Check Why
serve hosted Koog does not send our resume keys back; a confirm tool would never run
one HttpClient per app, closed on shutdown the transport keeps a connection open for server messages
everything on the public-host checklist

Sources