Proposal: Integrate Hermes MCP to function as MCP protocol layer

[mkschell]

Background

This was proposed in the ash_ai Discord channel and I've been working up a proof of concept. Since it looks imminently doable, I'm creating a more formal Proposal issue here. It's too soon for a PR, so this can serve as a place for focused collaboration on this feature.

Feature Description

Ultimately, the feature is to "not have to maintain and evolve a compliant MCP Server implementation".
Wrapped up with how we end up doing this, however, is the AshAi developer experience, so getting out of the gate on solid ground there is part of this proposal, even though I don't have a clear idea yet on what that can look like.

I'll share some progress, thoughts and questions shortly.

Alternatives

• continuing to evolve the in house MCP Server already in the library
• other MCP protocol implementations (?)

[mkschell]

Well one thing led to another and I've arrived at some working code that provides the following developer experience.

Define servers with compile time options

defmodule MyApp.PublicMcpServer do
  use AshAi.McpServer
    # all keywords optional
    name: "Admin Blog API",
    version: "2.0.0", 
    protocol_version: "2024-11-05",
    capabilities: [:tools]
    tools: [:list_posts, :create_post, :delete_post],
    actions: [{MyApp.Blog.Post, [:read, :create, :destroy]}],
    exclude_actions: [{MyApp.Blog.Post, :sensitive_action}],
end

defmodule MyApp.AdminMcpServer do  
  use AshAi.McpServer
end

Configure servers with runtime config

config :my_app, MyApp.PublicMcpServer,
  transport: :streamable_http,
  auth: [
    strategy: :api_key,
    resource: MyApp.Accounts.User,
    required?: false
  ]

config :my_app, MyApp.AdminMcpServer, transport: :stdio

Configure Application

# Add Servers to supervision tree
children = [
  # Start the Hermes MCP server registry
  Hermes.Server.Registry,
  # Start our MCP Servers
  MyApp.PublicMcpServer,
  MyApp.AdminMcpServer
]

Configure Router (for MCP Servers with a web transport)

  pipeline :mcp do
    plug :accepts, ["json"]

    # Gets a plug and opts based on the _auth_ key of the Server's runtime config
    {plug_mod, opts} = MyApp.McpAuth.from_config(MyApp.PublicMcpServer)
    plug plug_mod, opts
  end

  scope "/mcp" do
    pipe_through :mcp

    forward "/", Hermes.Server.Transport.StreamableHTTP.Plug, server: MyApp.PublicMcpServer
  end

This is the direction it's currently taking, but I'm interested in feedback on how this feels, and hopefully surface some stuff I haven't thought of. I'd be more than happy to move this in a different direction if there's a better dev ex to be had.

And if this direction looks ok, then I can get a PR going.

[zachdaniel]

IMO the big win of using Hermes (or something like it) is more than just getting the implementation, it's in using their abstraction for the server. This would allow people to use Hermes to mix together multiple tools into one, or add their own custom tools. I haven't looked at the details, but I'm imaginging something like this:

 use Hermes.McpServer, extensions: [{Ash..., tools: [...]}]

Thats just pseudocode, but the idea then is just that we provide a thin integration layer to add AshAi's MCP stuff to an MCP provided by the tool.

[mkschell]

using their abstraction for the server

So in my implementation at this point, use AshAi.McpServer is using their Server abstraction. You get a Hermes.McpServer from doing that.

mix together multiple tools into one

I'm not entirely sure what this means, but I can imagine accomplishing something like this

provide a thin integration layer to add AshAi's MCP stuff

I think this is what I've got going here, but I'm sure I'm squinting at it from a different angle than you are. Any module that uses AshAi.McpServer gets the full Hermes.McpServer api, or at least that's the vision.

Maybe it's PR time so I don't have to translate into English? ;-)

[zachdaniel]

Right, but what I mean is that the entry point should not be use AshAi.McpServer, but something that Hermes provides that allows you to mix in "n number of other things", one of which can be Ash. That may seem like a small detail, but its the trick that allows people to use AshAi's MCP tooling in conjunction with any other piece of tooling.

[mkschell]

Is there a similar pattern in play in another Ash library? I might need to see an example for my aha moment.

[zachdaniel]

The way we do it in AshGraphql for example, where you create an Absinthe schema and then you mix AshGraphql.Schema in. That allows you to define regular absinthe stuff in addition to your Ash stuff.

Or how AshJsonApi is just mounted inside your Phoenix router, it doesn't have its own dedicated entry point.

[mkschell]

Thanks for those examples. First thought looking at the AshGraphql example is that Absinthe has a DSL and extension points that make it quite possible to not invert the control like I guess my Hermes approach is doing. I'll keep digging and see if I can find an opportunity with Hermes. At the current time it feels like a very different beast.

[zachdaniel]

Ultimately if we can't achieve that inversion of control then I likely wouldn't want to move forward w/ using a separate tool for our MCP, at least not at this point.

[mkschell]

I hate to give up, as it's really not my thing. Ultimately at this time, Hermes does not have the extension points for approaching it like this and the metaprogramming to get there would be super fragile.

Sorry I wasn't able to get there. I'll probably continue this work for my own purposes since it's super compelling.

[zachdaniel]

I think it would be super valuable to start a conversation with the Hermes folks about what is missing to make it work. I think they'd be open to it :)

[mkschell]

I'm going to shift up a level, take a look at recent changes to Hermes, and map this thing out. Should I re-open this issue so we have a place to continue discussing the design? It seems weird to have an issue on AshAi to talk about changes we'd like in another library. Or I'm the weird one. Or both.

[zachdaniel]

I thinkt its fine to have this open 😄