ClaudeCode.MCP.Config (ClaudeCode v0.16.0)

Generates MCP configuration files for the Claude CLI.

The Claude CLI expects MCP server configurations in a specific JSON format. This module provides helpers to generate these configuration files for different transport types (HTTP/SSE and stdio).

Configuration Format

The Claude CLI expects a JSON file with the following structure:

{
  "mcpServers": {
    "server-name": {
      "command": "path/to/executable",
      "args": ["arg1", "arg2"],
      "env": {"KEY": "value"}
    }
  }
}

For HTTP/SSE transport:

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:9001/sse"
    }
  }
}

Usage

# Generate HTTP config
config = ClaudeCode.MCP.Config.http_config("my-server", port: 9001)

# Generate stdio config
config = ClaudeCode.MCP.Config.stdio_config("my-server",
  command: "elixir",
  args: ["-S", "mix", "run", "--no-halt", "-e", "MyApp.MCPServer.start_link()"]
)

# Write to temp file for Claude CLI
{:ok, path} = ClaudeCode.MCP.Config.write_temp_config(config)

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

Summary

Types

mcp_config()

server_config()

Functions

http_config(name, opts)

Generates an HTTP/SSE transport configuration for an MCP server.

merge_configs(configs)

Merges multiple MCP configurations into a single configuration.

stdio_config(name, opts)

Generates a stdio transport configuration for an MCP server.

to_json(config, opts \\ [])

Converts an MCP configuration to a JSON string.

write_temp_config(config, opts \\ [])

Writes an MCP configuration to a temporary file.

Types

mcp_config()

@type mcp_config() :: %{mcpServers: %{required(String.t()) => server_config()}}

server_config()

@type server_config() :: %{
  optional(:command) => String.t(),
  optional(:args) => [String.t()],
  optional(:env) => %{required(String.t()) => String.t()},
  optional(:url) => String.t()
}

Functions

http_config(name, opts)

@spec http_config(
  String.t(),
  keyword()
) :: mcp_config()

Generates an HTTP/SSE transport configuration for an MCP server.

Options

:port - Port number (required)
:host - Hostname (default: "localhost")
:path - SSE endpoint path (default: "/sse")
:scheme - URL scheme (default: "http")

Example

config = ClaudeCode.MCP.Config.http_config("calculator", port: 9001)
# => %{mcpServers: %{"calculator" => %{url: "http://localhost:9001/sse"}}}

config = ClaudeCode.MCP.Config.http_config("secure-server",
  port: 443,
  host: "api.example.com",
  scheme: "https",
  path: "/mcp/sse"
)

merge_configs(configs)

@spec merge_configs([mcp_config()]) :: mcp_config()

Merges multiple MCP configurations into a single configuration.

This is useful when you have multiple MCP servers that should all be available to Claude.

Example

calculator = ClaudeCode.MCP.Config.http_config("calculator", port: 9001)
database = ClaudeCode.MCP.Config.http_config("database", port: 9002)

merged = ClaudeCode.MCP.Config.merge_configs([calculator, database])
# => %{mcpServers: %{"calculator" => ..., "database" => ...}}

stdio_config(name, opts)

@spec stdio_config(
  String.t(),
  keyword()
) :: mcp_config()

Generates a stdio transport configuration for an MCP server.

Options

:command - Executable command (required)
:args - List of command arguments (default: [])
:env - Environment variables map (default: %{})

Example

config = ClaudeCode.MCP.Config.stdio_config("my-tools",
  command: "elixir",
  args: ["-S", "mix", "run", "--no-halt", "-e", "MyApp.start_mcp()"]
)

config = ClaudeCode.MCP.Config.stdio_config("node-server",
  command: "npx",
  args: ["@example/mcp-server"],
  env: %{"API_KEY" => "secret"}
)

to_json(config, opts \\ [])

@spec to_json(
  mcp_config(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Converts an MCP configuration to a JSON string.

Options

:pretty - Format with indentation (default: false)

Example

config = ClaudeCode.MCP.Config.http_config("my-server", port: 9001)
{:ok, json} = ClaudeCode.MCP.Config.to_json(config, pretty: true)

write_temp_config(config, opts \\ [])

@spec write_temp_config(
  mcp_config(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Writes an MCP configuration to a temporary file.

Returns the path to the temporary file, which can be passed to ClaudeCode via the :mcp_config option.

The temporary file is created in the system's temp directory and will be automatically cleaned up by the OS eventually.

Options

:prefix - Filename prefix (default: "claude_mcp_config")
:dir - Directory for temp file (default: System.tmp_dir!())

Example

config = ClaudeCode.MCP.Config.http_config("my-server", port: 9001)
{:ok, path} = ClaudeCode.MCP.Config.write_temp_config(config)

{:ok, session} = ClaudeCode.start_link(mcp_config: path)