Skip to main content Link Search Menu Expand Document (external link)

McpServer.ts overview

Since v1.0.0


Exports Grouped by Category


Constructors

run

Signature

declare const run: (options: {
  readonly name: string
  readonly version: string
}) => Effect.Effect<never, never, McpServer | RpcServer.Protocol>

Source

Since v1.0.0

Elicitation

elicit

Create an elicitation request

Signature

declare const elicit: <A, I extends Record<string, any>, R>(options: {
  readonly message: string
  readonly schema: Schema.Schema<A, I, R>
}) => Effect.Effect<A, ElicitationDeclined, McpServerClient | R>

Source

Since v1.0.0

Layers

layer

Signature

declare const layer: (options: {
  readonly name: string
  readonly version: string
}) => Layer.Layer<McpServer | McpServerClient, never, RpcServer.Protocol>

Source

Since v1.0.0

layerHttp

Run the McpServer, using HTTP for input and output.

import { McpSchema, McpServer } from "@effect/ai"
import { HttpRouter } from "@effect/platform"
import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
import { Effect, Layer, Schema } from "effect"
import { createServer } from "node:http"

const idParam = McpSchema.param("id", Schema.NumberFromString)

// Define a resource template for a README file
const ReadmeTemplate = McpServer.resource`file://readme/${idParam}`({
  name: "README Template",
  // You can add auto-completion for the ID parameter
  completion: {
    id: (_) => Effect.succeed([1, 2, 3, 4, 5])
  },
  content: Effect.fn(function* (_uri, id) {
    return `# MCP Server Demo - ID: ${id}`
  })
})

// Define a test prompt with parameters
const TestPrompt = McpServer.prompt({
  name: "Test Prompt",
  description: "A test prompt to demonstrate MCP server capabilities",
  parameters: Schema.Struct({
    flightNumber: Schema.String
  }),
  completion: {
    flightNumber: () => Effect.succeed(["FL123", "FL456", "FL789"])
  },
  content: ({ flightNumber }) => Effect.succeed(`Get the booking details for flight number: ${flightNumber}`)
})

// Merge all the resources and prompts into a single server layer
const ServerLayer = Layer.mergeAll(ReadmeTemplate, TestPrompt, HttpRouter.Default.serve()).pipe(
  // Provide the MCP server implementation
  Layer.provide(
    McpServer.layerHttp({
      name: "Demo Server",
      version: "1.0.0",
      path: "/mcp"
    })
  ),
  Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 }))
)

Layer.launch(ServerLayer).pipe(NodeRuntime.runMain)

Signature

declare const layerHttp: <I = HttpRouter.Default>(options: {
  readonly name: string
  readonly version: string
  readonly path: HttpRouter.PathInput
  readonly routerTag?: HttpRouter.HttpRouter.TagClass<I, string, any, any>
}) => Layer.Layer<McpServer | McpServerClient>

Source

Since v1.0.0

layerHttpRouter

Run the McpServer, using HTTP for input and output.

Uses a HttpLayerRouter to register the McpServer routes.

Signature

declare const layerHttpRouter: (options: {
  readonly name: string
  readonly version: string
  readonly path: HttpRouter.PathInput
}) => Layer.Layer<McpServer | McpServerClient, never, HttpLayerRouter.HttpRouter>

Source

Since v1.0.0

layerStdio

Run the McpServer, using stdio for input and output.

import { McpSchema, McpServer } from "@effect/ai"
import { NodeRuntime, NodeSink, NodeStream } from "@effect/platform-node"
import { Effect, Layer, Logger, Schema } from "effect"

const idParam = McpSchema.param("id", Schema.NumberFromString)

// Define a resource template for a README file
const ReadmeTemplate = McpServer.resource`file://readme/${idParam}`({
  name: "README Template",
  // You can add auto-completion for the ID parameter
  completion: {
    id: (_) => Effect.succeed([1, 2, 3, 4, 5])
  },
  content: Effect.fn(function* (_uri, id) {
    return `# MCP Server Demo - ID: ${id}`
  })
})

// Define a test prompt with parameters
const TestPrompt = McpServer.prompt({
  name: "Test Prompt",
  description: "A test prompt to demonstrate MCP server capabilities",
  parameters: Schema.Struct({
    flightNumber: Schema.String
  }),
  completion: {
    flightNumber: () => Effect.succeed(["FL123", "FL456", "FL789"])
  },
  content: ({ flightNumber }) => Effect.succeed(`Get the booking details for flight number: ${flightNumber}`)
})

// Merge all the resources and prompts into a single server layer
const ServerLayer = Layer.mergeAll(ReadmeTemplate, TestPrompt).pipe(
  // Provide the MCP server implementation
  Layer.provide(
    McpServer.layerStdio({
      name: "Demo Server",
      version: "1.0.0",
      stdin: NodeStream.stdin,
      stdout: NodeSink.stdout
    })
  ),
  // add a stderr logger
  Layer.provide(Logger.add(Logger.prettyLogger({ stderr: true })))
)

Layer.launch(ServerLayer).pipe(NodeRuntime.runMain)

Signature

declare const layerStdio: <EIn, RIn, EOut, ROut>(options: {
  readonly name: string
  readonly version: string
  readonly stdin: Stream<Uint8Array, EIn, RIn>
  readonly stdout: Sink<unknown, Uint8Array | string, unknown, EOut, ROut>
}) => Layer.Layer<McpServer | McpServerClient, never, RIn | ROut>

Source

Since v1.0.0

McpServer

McpServer (class)

Signature

declare class McpServer

Source

Since v1.0.0

Prompts

prompt

Register a prompt with the McpServer.

Signature

declare const prompt: <
  E,
  R,
  Params = {},
  ParamsI extends Record<string, string> = {},
  ParamsR = never,
  const Completions extends {
    readonly [K in keyof Params]?: (input: string) => Effect.Effect<Array<Params[K]>, any, any>
  } = {}
>(options: {
  readonly name: string
  readonly description?: string | undefined
  readonly parameters?: Schema.Schema<Params, ParamsI, ParamsR> | undefined
  readonly completion?: ValidateCompletions<Completions, Extract<keyof Params, string>> | undefined
  readonly content: (params: Params) => Effect.Effect<Array<typeof PromptMessage.Type> | string, E, R>
}) => Layer.Layer<never, never, Exclude<ParamsR | R, McpServerClient>>

Source

Since v1.0.0

registerPrompt

Register a prompt with the McpServer.

Signature

declare const registerPrompt: <
  E,
  R,
  Params = {},
  ParamsI extends Record<string, string> = {},
  ParamsR = never,
  const Completions extends {
    readonly [K in keyof Params]?: (input: string) => Effect.Effect<Array<Params[K]>, any, any>
  } = {}
>(options: {
  readonly name: string
  readonly description?: string | undefined
  readonly parameters?: Schema.Schema<Params, ParamsI, ParamsR> | undefined
  readonly completion?: ValidateCompletions<Completions, Extract<keyof Params, string>> | undefined
  readonly content: (params: Params) => Effect.Effect<Array<typeof PromptMessage.Type> | string, E, R>
}) => Effect.Effect<void, never, Exclude<ParamsR | R, McpServerClient> | McpServer>

Source

Since v1.0.0

Resources

registerResource

Register a resource with the McpServer.

Signature

declare const registerResource: {
  <E, R>(options: {
    readonly uri: string
    readonly name: string
    readonly description?: string | undefined
    readonly mimeType?: string | undefined
    readonly audience?: ReadonlyArray<"user" | "assistant"> | undefined
    readonly priority?: number | undefined
    readonly content: Effect.Effect<typeof ReadResourceResult.Type | string | Uint8Array, E, R>
  }): Effect.Effect<void, never, Exclude<R, McpServerClient> | McpServer>
  <const Schemas extends ReadonlyArray<Schema.Schema.Any>>(
    segments: TemplateStringsArray,
    ...schemas: Schemas & {
      readonly [K in keyof Schemas]: Schema.Schema.Encoded<Schemas[K]> extends string
        ? unknown
        : "Schema must be encodable to a string"
    }
  ): <E, R, const Completions extends Partial<ResourceCompletions<Schemas>> = {}>(options: {
    readonly name: string
    readonly description?: string | undefined
    readonly mimeType?: string | undefined
    readonly audience?: ReadonlyArray<"user" | "assistant"> | undefined
    readonly priority?: number | undefined
    readonly completion?: ValidateCompletions<Completions, keyof ResourceCompletions<Schemas>> | undefined
    readonly content: (
      uri: string,
      ...params: { readonly [K in keyof Schemas]: Schemas[K]["Type"] }
    ) => Effect.Effect<typeof ReadResourceResult.Type | string | Uint8Array, E, R>
  }) => Effect.Effect<
    void,
    never,
    | Exclude<
        | R
        | (Completions[keyof Completions] extends (input: string) => infer Ret
            ? Ret extends Effect.Effect<infer _A, infer _E, infer _R>
              ? _R
              : never
            : never),
        McpServerClient
      >
    | McpServer
  >
}

Source

Since v1.0.0

resource

Register a resource with the McpServer.

Signature

declare const resource: {
  <E, R>(options: {
    readonly uri: string
    readonly name: string
    readonly description?: string | undefined
    readonly mimeType?: string | undefined
    readonly audience?: ReadonlyArray<"user" | "assistant"> | undefined
    readonly priority?: number | undefined
    readonly content: Effect.Effect<typeof ReadResourceResult.Type | string | Uint8Array, E, R>
  }): Layer.Layer<never, never, Exclude<R, McpServerClient>>
  <const Schemas extends ReadonlyArray<Schema.Schema.Any>>(
    segments: TemplateStringsArray,
    ...schemas: Schemas & {
      readonly [K in keyof Schemas]: Schema.Schema.Encoded<Schemas[K]> extends string
        ? unknown
        : "Schema must be encodable to a string"
    }
  ): <E, R, const Completions extends Partial<ResourceCompletions<Schemas>> = {}>(options: {
    readonly name: string
    readonly description?: string | undefined
    readonly mimeType?: string | undefined
    readonly audience?: ReadonlyArray<"user" | "assistant"> | undefined
    readonly priority?: number | undefined
    readonly completion?: ValidateCompletions<Completions, keyof ResourceCompletions<Schemas>> | undefined
    readonly content: (
      uri: string,
      ...params: { readonly [K in keyof Schemas]: Schemas[K]["Type"] }
    ) => Effect.Effect<typeof ReadResourceResult.Type | string | Uint8Array, E, R>
  }) => Layer.Layer<
    never,
    never,
    Exclude<
      | R
      | (Completions[keyof Completions] extends (input: string) => infer Ret
          ? Ret extends Effect.Effect<infer _A, infer _E, infer _R>
            ? _R
            : never
          : never),
      McpServerClient
    >
  >
}

Source

Since v1.0.0

Tools

registerToolkit

Register an AiToolkit with the McpServer.

Signature

declare const registerToolkit: <Tools extends AiTool.Any>(
  toolkit: AiToolkit.AiToolkit<Tools>
) => Effect.Effect<void, never, McpServer | AiTool.ToHandler<Tools> | Exclude<AiTool.Context<Tools>, McpServerClient>>

Source

Since v1.0.0

toolkit

Register an AiToolkit with the McpServer.

Signature

declare const toolkit: <Tools extends AiTool.Any>(
  toolkit: AiToolkit.AiToolkit<Tools>
) => Layer.Layer<never, never, AiTool.ToHandler<Tools> | Exclude<AiTool.Context<Tools>, McpServerClient>>

Source

Since v1.0.0

utils

ResourceCompletions (type alias)

Signature

type ResourceCompletions<Schemas> = {
  readonly [K in Extract<keyof Schemas, `${number}`> as Schemas[K] extends Param<infer Id, infer _S>
    ? Id
    : `param${K}`]: (input: string) => Effect.Effect<Array<Schema.Schema.Type<Schemas[K]>>, any, any>
}

Source

Since v1.0.0

ValidateCompletions (type alias)

Signature

type ValidateCompletions<Completions, Keys> = Completions & {
  readonly [K in keyof Completions]: K extends Keys ? (input: string) => any : never
}

Source

Since v1.0.0