Introduction

Modern AI applications don’t live in a vacuum—they need access to tools, data, and workflows that sit beyond the LLM itself. The Model Context Protocol (MCP) standardizes how an AI host (your app/agent platform) discovers and safely uses those external capabilities via a client–server model. Helidon MCP brings a first-class, cloud-native implementation of an MCP server to the Java ecosystem, offering both declarative and imperative styles so teams can move fast and retain fine-grained control.

Quick refresher: What is MCP?

MCP is an open protocol (JSON-RPC 2.0 at the data layer; multiple transports at the connection layer) that separates how context is exchanged from how models are used. In practice, your AI host speaks to one or more MCP clients (one per server), and those clients connect to MCP servers that expose:

  • Tools – executable actions (tools/list, tools/call)
  • Resources – addressable context data (resources/list, resources/read, templates)
  • Prompts – reusable, parameterized interaction templates (prompts/list, prompts/get)

Clients can also provide sampling (LLM calls on behalf of servers), elicitation (asking the user for structured inputs), and logging/notifications (e.g., list_changed events, progress). Transports include Streamable HTTP with optional HTTP SSE for server-to-client streaming (Helidon focuses on these transports).

MCP Architecture

Why Helidon MCP?

Helidon MCP gives you a lightweight, cloud-native Java server that:

  • Uses virtual threads to scale with minimal ceremony
  • Avoids heavy third-party dependencies
  • Integrates naturally with Helidon’s routing and config
  • Supports the latest MCP features (tools/resources/prompts, logging, progress, pagination, cancellation) over Streamable HTTP / HTTP SSE (stdio intentionally not supported in Helidon MCP).

This is ideal for enterprise teams standardizing AI integrations behind clear contracts, approvals, and observability.

Two ways to build: Declarative vs Imperative

Helidon MCP offers two complementary patterns:

Declarative (annotation-driven)

  • Define Tools, Resources, Prompts, and Completions with annotations.
  • Map method parameters to JSON Schema automatically; use POJOs for richer types.
  • Fastest path to a working server; great defaults, less boilerplate.

When to choose it: POCs, greenfield services, or when you want a clean contract with minimal code.

Imperative (builder-driven)

  • Build the server via builders and register endpoints with Helidon routing.
  • Full control to customize lifecycle, registration, and behavior.
  • Same runtime benefits (virtual threads, lightweight footprint).

When to choose it: You need fine-grained hooks, specialized routing, or to align with an existing microservice style.

Declarative_vs_Imperative

What you expose to the AI host

  • Tools – small, purposeful functions. Example: get_weather(state="NY"). The host can surface tools for explicit user approval, then call them with validated inputs; the server returns structured content[].
  • Resources – URIs for data (files, APIs, DBs), with declared media types and optional parameterized templates (e.g., weather://forecast/{city}/{date}). Hosts can subscribe or selectively inject content.
  • Prompts – reusable templates that standardize interactions; validated arguments reduce LLM ambiguity.
  • Completions – hints for filling prompt arguments or resource templates that improve UX and robustness.

Helidon MCP ships logging (server→client diagnostic messages) and progress notifications—crucial for long-running actions and user trust. Pagination and cancellation round out production-grade ergonomics.

A typical request flow (weather demo)

  1. User asks: “What’s the weather in NY?”
  2. AI Host (agent platform) initializes the MCP client session and fetches available context (tools/resources/prompts).
  3. The host (or model) selects get_weather and calls it with validated args ({ state: "NY" }).
  4. Helidon MCP Server calls the upstream Weather REST service, formats a response, and streams progress/logs back via SSE as needed.
  5. The host returns structured content to the user.

Demo Flow

Transport choices and security posture

  • Streamable HTTP is the primary transport: multiple client connections, POST/GET, optional SSE for server→client streaming.
  • HTTP SSE (or HTTP+SSE) is the older transport now being replaced by Streamable HTTP.
  • Human-in-the-loop approvals and scoped capabilities/roots are central to safe operations—keep tool calls explicit and auditable.
  • Use bearer headers/keys; OAuth is recommended in enterprise deployments.

Developer experience highlights

  • Fast scaffolding with annotations; move to imperative bits where bespoke control is required.
  • Rich schema mapping for tool arguments (primitives → JSON Schema, POJOs for complex inputs).
  • Observability built-in (logging/progress), with clear user affordances in the host.
  • Language ecosystem fit: Java teams keep their existing CI/CD, testing, and SLAs while unlocking MCP.

How to introduce Helidon MCP in your stack

  1. Start declarative to stand up a thin MCP façade over one or two high-value tools (e.g., read-only business KPIs, a forecast API).
  2. Layer resources and prompts to standardize common contexts and interactions for the LLM.
  3. Add completions to reduce invalid inputs and improve your host’s UX.
  4. Instrument progress/logging and wire approvals to your existing change-control or human-in-the-loop patterns.
  5. Shift to imperative pieces where you need custom routing, advanced auth, or cross-cutting concerns.
  6. Scale horizontally; virtual threads handle concurrency, and HTTP SSE/Streamable HTTP keeps users informed during longer operations.

Secure Helidon MCP Server with Oracle Identity Domain

This companion blog will walk you through protecting your Helidon MCP endpoints with Oracle Identity Domain:

  • MCP Security Flow
  • OAuth Client Application in Identity Domain
  • Access Token Validation
  • Helidon Open ID Connect with Oracle Identity Domain
  • Securing Helidon MCP Server
  • Testing with MCP Inspector and Postman