ClaudeCode.MCP.Server (ClaudeCode v0.16.0)

Helper for starting and managing Hermes MCP servers for use with ClaudeCode.

This module provides convenience functions to start Hermes MCP servers and automatically generate the configuration files needed by the Claude CLI.

Prerequisites

This module requires the hermes_mcp dependency:

{:hermes_mcp, "~> 0.14"}

Usage

Starting an HTTP Server

# Define your Hermes server module
defmodule MyApp.MCPServer do
  use Hermes.Server,
    name: "my-tools",
    version: "1.0.0"

  tool MyApp.Calculator
  tool MyApp.FileReader
end

# Start the server and get config path
{:ok, config_path} = ClaudeCode.MCP.Server.start_link(MyApp.MCPServer, port: 9001)

# Use with ClaudeCode
{:ok, session} = ClaudeCode.start_link(mcp_config: config_path)

With Supervision

# In your application supervisor
children = [
  {ClaudeCode.MCP.Server, server: MyApp.MCPServer, port: 9001, name: :my_mcp}
]

Architecture

When started, this module:

Validates that Hermes MCP is available
Starts the Hermes server with HTTP transport
Generates an MCP config file pointing to the server
Returns the config file path for use with ClaudeCode

Summary

Types

start_option()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_config_path(server)

Gets the config path from a running MCP server.

start_link(opts)

Starts an MCP server as a linked process.

stdio_command(opts)

Generates a stdio command configuration for a Hermes server.

Types

start_option()

@type start_option() ::
  {:server, module()}
  | {:port, pos_integer()}
  | {:host, String.t()}
  | {:name, GenServer.name()}
  | {:hermes_opts, keyword()}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_config_path(server)

@spec get_config_path(GenServer.server()) :: String.t()

Gets the config path from a running MCP server.

Example

config_path = ClaudeCode.MCP.Server.get_config_path(:my_mcp)

start_link(opts)

@spec start_link([start_option()]) :: {:ok, String.t()} | {:error, term()}

Starts an MCP server as a linked process.

Options

:server - The Hermes server module (required)
:port - Port for HTTP transport (required)
:host - Hostname to bind (default: "localhost")
:name - GenServer name for this process (optional)
:hermes_opts - Additional options passed to Hermes.Server.start_link/1

Returns

{:ok, config_path} - Path to the generated MCP config file
{:error, reason} - If startup fails

Example

{:ok, config_path} = ClaudeCode.MCP.Server.start_link(
  server: MyApp.MCPServer,
  port: 9001
)

stdio_command(opts)

@spec stdio_command(keyword()) :: %{
  command: String.t(),
  args: [String.t()],
  env: %{required(String.t()) => String.t()}
}

Generates a stdio command configuration for a Hermes server.

This creates the command and args needed to start a Hermes server as a subprocess using stdio transport.

Options

:module - The Hermes server module (required)
:mix_env - Mix environment (default: "prod")

Example

config = ClaudeCode.MCP.Server.stdio_command(
  module: MyApp.MCPServer
)
# => %{command: "mix", args: ["run", "--no-halt", "-e", "..."]}