Package akka.javasdk.agent

Interface RemoteMcpTools

@DoNotInherit public interface RemoteMcpTools
Configuration for accessing tools from remote Model Context Protocol (MCP) servers.

MCP servers provide tools that agents can use to extend their capabilities. This class allows agents to connect to remote MCP servers and use their tools, including third-party services and other Akka services with MCP endpoints.

Security: When using MCP endpoints in other Akka services, service ACLs apply just like for HTTP and gRPC endpoints. For third-party MCP servers, use HTTPS and appropriate authentication headers.

Tool Filtering: You can control which tools from the MCP server are available to the agent using tool name filters or explicit allow lists.

Not for user extension, create instances using fromServer(String) or fromService(String).

  • Method Details

    • fromServer

      static RemoteMcpTools fromServer(String serverUri)
      Parameters:
      serverUri - A URI to the remote MCP HTTP server, for example "https://example.com/sse" or "https://example.com/mcp

    • fromService

      static RemoteMcpTools fromService(String serviceName)
      Parameters:
      serviceName - A service name of another Akka service with an MCP endpoint in the default path /mcp

    • withToolNameFilter

      RemoteMcpTools withToolNameFilter(Predicate<String> toolNameFilter)
      Define a filter to select what discovered tool names are passed on to the chat model. Names that are filtered will not be described to the model and will not allow calls. Will override a previous call to withAllowedToolNames(Set).

      By default, all tools are allowed.

    • withAllowedToolNames

      RemoteMcpTools withAllowedToolNames(Set<String> allowedToolNames)
      Define a set of allowed tool names. Will override a previously defined withToolNameFilter(Predicate)

      By default, all tools are allowed.

    • withAllowedToolNames

      RemoteMcpTools withAllowedToolNames(String allowedToolName, String... moreAllowedToolNames)
      Define a set of allowed tool names. Will override a previously defined withToolNameFilter(Predicate)

      By default, all tools are allowed.

    • withToolInterceptor

      RemoteMcpTools withToolInterceptor(RemoteMcpTools.ToolInterceptor interceptor)
      Specify an interceptor that has the capability to allow or deny calls (by throwing an exception) and also to modify and filter input to the MCP server tool.

    • addClientHeader

      RemoteMcpTools addClientHeader(akka.http.javadsl.model.HttpHeader header)
      Parameters:
      header - A header that should be passed with each call to the MCP server, for example some authentication token in an OAuth2BearerToken

    • withTimeout

      RemoteMcpTools withTimeout(Duration timeout)
      Parameters:
      timeout - A max time any MCP request may take before it is failed. If not specified a default timeout of 20s applies.