mcp_client

gleam_mcp — MCP (Model Context Protocol) client for Gleam.

Public facade for the gleam_mcp package. Provides an ergonomic API for connecting to MCP servers, discovering tools/resources/prompts, and invoking them via JSON-RPC 2.0 over STDIO.

Quick start

import mcp_client
import gleam/dict

pub fn main() {
  let assert Ok(client) = gleam_mcp.new()

  let config = gleam_mcp.ServerConfig(
    name: "filesystem",
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    env: [],
    retry: gleam_mcp.no_retry,
  )
  let assert Ok(Nil) = gleam_mcp.register(client, config)

  let tools = gleam_mcp.tools(client)
  let assert Ok(result) = gleam_mcp.call(client, "filesystem/list_directory", "{\"path\":\"/tmp\"}")

  gleam_mcp.stop(client)
}

Types

Client

</>

An MCP client handle (opaque actor subject).

pub type Client =
  process.Subject(manager.ManagerMessage)

Prompt

</>

A discovered prompt template from an MCP server.

pub type Prompt =
  manager.Prompt

PromptArg

</>

An argument definition for an MCP prompt.

pub type PromptArg =
  manager.PromptArg

Resource

</>

A discovered resource from an MCP server.

pub type Resource =
  manager.Resource

RetryPolicy

</>

Retry policy applied when a server process crashes.

pub type RetryPolicy =
  manager.RetryPolicy

ServerConfig

</>

Configuration for an MCP server connection.

pub type ServerConfig =
  manager.ServerConfig

Tool

</>

A discovered tool from an MCP server. tool.spec.name is the qualified name: "server_name/tool_name". tool.original_name is the bare name as declared by the server.

pub type Tool =
  manager.Tool

ToolSpec

</>

A minimal tool specification (name + description).

pub type ToolSpec =
  manager.ToolSpec

Values

call

</>

pub fn call(
  client: process.Subject(manager.ManagerMessage),
  tool: String,
  args: String,
) -> Result(String, String)

Call a tool by its qualified name with JSON-encoded arguments.

The tool argument must be "server_name/tool_name". The args parameter is a JSON object string matching the tool’s input schema. Returns the raw JSON result string.

Example

let assert Ok(result) = gleam_mcp.call(
  client,
  "filesystem/read_file",
  "{\"path\":\"/etc/hostname\"}",
)

new

</>

pub fn new() -> Result(
  process.Subject(manager.ManagerMessage),
  actor.StartError,
)

Create a new MCP client.

Example

let assert Ok(client) = gleam_mcp.new()

no_retry

</>

pub const no_retry: manager.RetryPolicy

Do not retry on server crash — remove the server from state immediately.

prompt

</>

pub fn prompt(
  client: process.Subject(manager.ManagerMessage),
  server: String,
  name: String,
  args: dict.Dict(String, String),
) -> Result(String, String)

Get a rendered prompt from a named server.

args is a Dict(String, String) of argument name → value pairs. Returns the raw JSON result string from the prompts/get response.

Example

let assert Ok(result) = gleam_mcp.prompt(
  client, "myserver", "summarize",
  dict.from_list([#("text", "Hello world")]),
)

prompts

</>

pub fn prompts(
  client: process.Subject(manager.ManagerMessage),
) -> List(manager.Prompt)

List all prompt templates discovered across all registered servers.

read

</>

pub fn read(
  client: process.Subject(manager.ManagerMessage),
  server: String,
  uri: String,
) -> Result(String, String)

Read a resource by URI from a named server.

Returns the raw JSON result string from the resources/read response.

Example

let assert Ok(result) = gleam_mcp.read(client, "filesystem", "file:///etc/hostname")

register

</>

pub fn register(
  client: process.Subject(manager.ManagerMessage),
  config: manager.ServerConfig,
) -> Result(Nil, String)

Starts the server process, runs the MCP initialize sequence, and discovers all available tools, resources, and prompts.

Example

let config = gleam_mcp.ServerConfig(
  name: "github",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: [#("GITHUB_PERSONAL_ACCESS_TOKEN", "ghp_...")],
  retry: gleam_mcp.retry(3, 500),
)
let assert Ok(Nil) = gleam_mcp.register(client, config)

resources

</>

pub fn resources(
  client: process.Subject(manager.ManagerMessage),
) -> List(manager.Resource)

List all resources discovered across all registered servers.

retry

</>

pub fn retry(
  max_attempts: Int,
  base_delay_ms: Int,
) -> manager.RetryPolicy

Retry on server crash with exponential backoff.

Example

gleam_mcp.retry(max_attempts: 3, base_delay_ms: 500)

servers

</>

pub fn servers(
  client: process.Subject(manager.ManagerMessage),
) -> List(String)

List the names of all currently registered servers.

stop

</>

pub fn stop(
  client: process.Subject(manager.ManagerMessage),
) -> Nil

Stop the client and all server connections.

tools

</>

pub fn tools(
  client: process.Subject(manager.ManagerMessage),
) -> List(manager.Tool)

List all tools discovered across all registered servers.

Tool names are qualified: "server_name/tool_name".

unregister

</>

pub fn unregister(
  client: process.Subject(manager.ManagerMessage),
  name: String,
) -> Result(Nil, String)

Unregister an MCP server and stop its process.

Also removes all tools, resources, and prompts discovered from that server.