Components

Copy Markdown View Source

FastestMCP supports the four core MCP component types:

  • tools
  • resources
  • resource templates
  • prompts

All of them are declared on the same server definition and executed through the same runtime pipeline. That is why list, call, read, render, middleware, visibility, auth, and provider composition stay aligned.

Choosing The Right Component Type

Use:

  • a tool when the client is asking the server to perform work
  • a resource when the client is reading a stable named object by URI
  • a resource template when the URI shape is dynamic
  • a prompt when the server is returning message content intended for model use

The distinction matters because MCP clients treat these surfaces differently.

For detailed usage, see the focused guides:

Tools

Tools are the action surface. They are the right choice when the caller wants the server to do work:

  • call an external API
  • compute a value
  • run a workflow
  • mutate application state

Resources

Resources are the read surface. They are the right choice when the caller is reading a named object or document by URI.

That includes both:

  • fixed resources such as config://release
  • dynamic resource templates such as users://{id}

Prompts

Prompts are reusable message templates. They are the right choice when the result is model-facing content rather than an action or a URI-addressable data read.

Shared Metadata

Most component types share the same shaping options:

  • description
  • title
  • version
  • task
  • tags
  • visibility
  • meta

Tools also support annotations, input_schema, and output_schema. Resources and prompts can also participate in task execution and visibility rules, just like tools.

Common Helper Shapes

FastestMCP keeps helper types explicit in the builder API and handler return values.

Prompt helpers:

alias FastestMCP.Prompts.Message
alias FastestMCP.Prompts.Result

FastestMCP.add_prompt(server, "review", fn _arguments, _ctx ->
  Result.new([
    Message.new("Review this diff"),
    Message.new("Done.", role: :assistant)
  ])
end)

Tool helper:

alias FastestMCP.Tools.Result

FastestMCP.add_tool(server, "release_report", fn _arguments, _ctx ->
  Result.new(
    "Release checklist generated",
    structured_content: %{status: "ok", checks: ["docs", "tests", "publish"]}
  )
end)

Resource helpers:

alias FastestMCP.Resources.Directory
alias FastestMCP.Resources.File
alias FastestMCP.Resources.Result
alias FastestMCP.Resources.Text

file = File.new("/tmp/report.txt")
directory = Directory.new("/tmp/reports", recursive: true)

FastestMCP.add_resource(server, "file:///tmp/report.txt", fn _arguments, _ctx ->
  File.read(file)
end)

FastestMCP.add_resource(server, "dir:///tmp/reports", fn _arguments, _ctx ->
  Directory.read(directory)
end)

FastestMCP.add_resource(server, "memo://inline", fn _arguments, _ctx ->
  Result.new([Text.new("hello")])
end)

Context convenience:

FastestMCP.add_tool(server, "request_info", fn _arguments, ctx ->
  request = FastestMCP.Context.request_context(ctx)

  %{
    request_id: request.request_id,
    client_id: FastestMCP.Context.client_id(ctx)
  }
end)

These surfaces stay explicit in the server definition and handler code.

Listing and Calling

FastestMCP.list_tools(MyApp.MCPServer)
FastestMCP.list_resources(MyApp.MCPServer)
FastestMCP.list_resource_templates(MyApp.MCPServer)
FastestMCP.list_prompts(MyApp.MCPServer)

FastestMCP.call_tool(MyApp.MCPServer, "sum", %{"a" => 20, "b" => 22})
FastestMCP.read_resource(MyApp.MCPServer, "users://42")
FastestMCP.render_prompt(MyApp.MCPServer, "welcome", %{"name" => "Nate"})

These operations stay aligned whether the component came from:

  • the base server definition
  • a mounted server
  • a standalone provider
  • the component manager

Components and Other Features

Component definitions are where several other runtime features meet:

  • Tools: action-specific validation, result shaping, annotations, and task semantics
  • Resources: URI-based reads, template matching, MIME typing, and read-task behavior
  • Prompts: reusable message templates and prompt argument metadata
  • Background Tasks: task: can be enabled per component
  • Versioning and Visibility: version and audience rules live on component metadata
  • Transforms: transforms can rewrite or hide components before they are exposed
  • Providers and Mounting: providers are another source of components

Why This Shape

FastestMCP keeps one declarative component model and one execution pipeline.

That avoids the common failure mode where tools, resources, prompts, and generated provider surfaces slowly drift into separate subsystems with slightly different behavior. In FastestMCP, they are different component types, not different runtime architectures.