FastestMCP

https://hexdocs.pm/fastest_mcp
Admin
FastestMCP provides OTP-native Model Context Protocol (MCP) servers and clients with supervised...
Tokens:4,028
Snippets:30
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Define a server with tool, resource, template, and prompt using FastestMCP.server/2

Source: https://hexdocs.pm/fastest_mcp

Composes a server definition with a tool, resource, resource template, and prompt. The tool uses an input schema with an enum for environment, returns a result with structured content, and the prompt takes an argument. The server is started with FastestMCP.start_server/1. Use FastestMCP.ServerModule for supervision tree definitions; use FastestMCP.server/2 for dynamic definitions, tests, and provider composition.

```elixir
input_schema = %{
  "type" => "object",
  "properties" => %{
    "environment" => %{
      "type" => "string",
      "enum" => ["staging", "production"]
    }
  },
  "required" => ["environment"]
}

server =
  FastestMCP.server("operations")
  |> FastestMCP.add_tool(
    "deployment_status",
    fn %{"environment" => environment}, _ctx ->
      FastestMCP.Tools.Result.new(
        "#{environment} is healthy",
        structured_content: %{environment: environment, status: "healthy"}
      )
    end,
    description: "Read the current deployment status",
    input_schema: input_schema
  )
  |> FastestMCP.add_resource("config://environments", fn _arguments, _ctx ->
    %{environments: ["staging", "production"]}
  end)
  |> FastestMCP.add_resource_template(
    "deployments://{environment}/latest",
    fn %{"environment" => environment}, _ctx ->
      %{environment: environment, revision: "2026.08.14", status: "healthy"}
    end
  )
  |> FastestMCP.add_prompt(
    "review_deployment",
    fn %{"environment" => environment}, _ctx ->
      "Review the latest #{environment} deployment and identify operational risks."
    end,
    arguments: [%{name: "environment", required: true}]
  )

{:ok, _pid} = FastestMCP.start_server(server)
```

--------------------------------

### Define a module-owned MCP server with tools

Source: https://hexdocs.pm/fastest_mcp

Defines a module-owned server using FastestMCP.ServerModule, adding a 'sum' tool and a 'visit' tool that uses context state. The server is started as a child in a supervision tree and called with FastestMCP.call_tool.

```elixir
defmodule MyApp.MCPServer do
  use FastestMCP.ServerModule,
    http: [port: 4100, allowed_hosts: :localhost]

  alias FastestMCP.Context

  def server(opts) do
    base_server(opts)
    |> FastestMCP.add_tool("sum", fn %{"a" => a, "b" => b}, _ctx -> a + b end)
    |> FastestMCP.add_tool("visit", fn _arguments, ctx ->
      visits = Context.get_state(ctx, :visits, 0) + 1
      :ok = Context.set_state(ctx, :visits, visits)
      %{visits: visits, server: ctx.server_name}
    end)
  end
end

children = [
  MyApp.MCPServer
]

FastestMCP.call_tool(MyApp.MCPServer, "sum", %{"a" => 20, "b" => 22})
# => 42
```

--------------------------------

### Supervise a named MCP client connection

Source: https://hexdocs.pm/fastest_mcp

Starts a supervised, named FastestMCP.Client connection, waits for it to be ready, and lists available tools. Suitable for production applications.

```elixir
children = [
  {FastestMCP.Client,
   target: "http://localhost:4100/mcp",
   name: MyApp.MCPClient,
   protocol_version: :auto}
]

:ok = FastestMCP.Client.await_ready(MyApp.MCPClient, 10_000)
%{items: tools} = FastestMCP.Client.list_tools(MyApp.MCPClient)
```

--------------------------------

### Connect to MCP server over HTTP with automatic protocol negotiation

Source: https://hexdocs.pm/fastest_mcp

Connects to a running MCP server over HTTP with automatic latest-first protocol negotiation, calls the 'sum' tool, starts and cancels a 'slow_sum' tool result, and disconnects. Demonstrates client operations and cancellation.

```elixir
client =
  FastestMCP.Client.connect!("http://localhost:4100/mcp",
    protocol_version: :auto,
    client_info: %{"name" => "my_app", "version" => "1.0.0"}
  )

FastestMCP.Client.protocol_version(client)
# => "2026-07-28"

%FastestMCP.Client.ToolResult{structured_content: 42} =
  FastestMCP.Client.call_tool_result(client, "sum", %{"a" => 20, "b" => 22})

request =
  FastestMCP.Client.start_tool_result(client, "slow_sum", %{"a" => 20, "b" => 22})

# This remains valid if tools/call becomes a negotiated remote task.
:ok = FastestMCP.Client.cancel_tool_result(request, "no longer needed")

:ok = FastestMCP.Client.disconnect(client)
```

--------------------------------

### Define an MCP App with tool and resource

Source: https://hexdocs.pm/fastest_mcp

Shows how to create an MCP App by adding a tool and a resource with Apps metadata. The tool returns a text fallback and structured content, while the resource serves an HTML document with CSP and border options. Requires the Apps extension to be enabled on the server.

```elixir
alias FastestMCP.Apps

app_uri = "ui://reports/summary.html"
app_options = [
  csp: %{"connectDomains" => ["https://api.example.com"]},
  prefers_border: true
]

server =
  FastestMCP.server("reports",
    extensions: %{Apps.extension_id() => %{}}
  )
  |> FastestMCP.add_tool(
    "show_report",
    fn _arguments, _ctx ->
      FastestMCP.Tools.Result.new(
        "The report is ready.",
        structured_content: %{status: "ready"}
      )
    end,
    meta: Apps.tool_meta(app_uri)
  )
  |> FastestMCP.add_resource(
    app_uri,
    fn _arguments, _ctx ->
      Apps.result(
        app_uri,
        "<!doctype html><html><body><main>Report</main></body></html>",
        app_options
      )
    end,
    mime_type: Apps.mime_type(),
    meta: Apps.resource_meta(app_options)
  )
```

--------------------------------

### Query supported and current protocol versions

Source: https://hexdocs.pm/fastest_mcp

Shows how to retrieve the list of supported MCP protocol versions and the current default version. The output comments indicate the expected return values: a list of both supported versions and the current version string.

```elixir
FastestMCP.supported_protocol_versions()
# => ["2026-07-28", "2025-11-25"]

FastestMCP.current_protocol_version()
# => "2026-07-28"
```

--------------------------------

### Fetch dependencies with mix deps.get

Source: https://hexdocs.pm/fastest_mcp

Fetches the project dependencies after adding fastest_mcp.

```shell
mix deps.get
```

--------------------------------

### Client opts into Apps MIME type

Source: https://hexdocs.pm/fastest_mcp

Shows how a client connects with the Apps extension enabled, using client settings to opt into the supported Apps MIME type.

```elixir
client =
  FastestMCP.Client.connect!(endpoint,
    extensions: %{Apps.extension_id() => Apps.client_settings()}
  )
```

--------------------------------

### Add MCP server to supervision tree

Source: https://hexdocs.pm/fastest_mcp

Shows the children list for the application supervision tree, placing MyApp.MCPServer before MyAppWeb.Endpoint.

```elixir
children = [
  MyApp.Repo,
  MyApp.MCPServer,
  MyAppWeb.Endpoint
]
```

--------------------------------

### Mount discovery and MCP endpoints with authentication pipeline

Source: https://hexdocs.pm/fastest_mcp

Defines a non-halting authentication pipeline and mounts the well-known discovery route publicly and the MCP endpoint behind the pipeline. The verifier must not redirect or halt; FastestMCP handles 401/403 responses.

```elixir
pipeline :mcp_auth do
  # Verifies signature/introspection, issuer, expiry, audience, and scopes.
  # It assigns :mcp_identity when valid, but never redirects or halts.
  plug MyAppWeb.MCPBearerVerifier
end

scope "/" do
  forward "/.well-known/oauth-protected-resource/mcp",
          FastestMCP.Transport.WellKnownHTTP,
    server_name: MyApp.MCPServer,
    path: "/mcp",
    base_url: "https://mcp.example.com",
    allowed_hosts: ["mcp.example.com"]
end

scope "/" do
  pipe_through :mcp_auth

  forward "/mcp", FastestMCP.Transport.HTTPApp,
    server_name: MyApp.MCPServer,
    path: "/mcp",
    base_url: "https://mcp.example.com",
    allowed_hosts: ["mcp.example.com"],
    auth_assigns: [:mcp_identity]
end
```

--------------------------------

### Define Phoenix MCP server module with authentication

Source: https://hexdocs.pm/fastest_mcp

Defines an MCP server module supervised by Phoenix, using FastestMCP.ServerModule with protected resource configuration and authentication from Phoenix assigns. The server adds a tool that requires the 'reports:write' scope.

```elixir
defmodule MyApp.MCPServer do
  use FastestMCP.ServerModule,
    otp_app: :my_app,
    protected_resource: [
      resource: "https://mcp.example.com/mcp",
      authorization_servers: ["https://auth.example.com"],
      scopes_supported: ["reports:read", "reports:write"],
      required_scopes: ["reports:read"]
    ]

  def server(opts) do
    base_server(opts)
    |> FastestMCP.add_auth(
      FastestMCP.Auth.from_assign(:mcp_identity,
        principal: fn identity -> {identity.issuer, identity.subject} end,
        audiences: fn identity -> identity.verified_audiences end,
        scopes: fn identity -> identity.verified_scopes end,
        auth: fn identity -> %{source: :phoenix, subject: identity.subject} end
      )
    )
    |> FastestMCP.add_tool(
      "create_report",
      fn arguments, ctx -> MyApp.Reports.create!(arguments, actor: ctx.principal) end,
      auth: FastestMCP.Authorization.require_scopes(["reports:write"])
    )
  end
end
```

--------------------------------

### Add FastestMCP dependency

Source: https://hexdocs.pm/fastest_mcp

Adds the fastest_mcp package to a Mix project's dependencies. Requires Elixir and Mix.

```elixir
def deps do
  [
    {:fastest_mcp, "~> 0.3.1"}
  ]
end
```
Tokens:
Raw