Skip to content
Effect Days 2026 Get your ticket

McpServer

15 exports Added in v1.0.0 Source

Constructors

run

Added in v1.0.0 Source

Signature

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

Elicitation

elicit

Added in v1.0.0 Source

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>

Layers

layer

Added in v1.0.0 Source

Signature

declare function layer(options: {
  readonly name: string;
  readonly version: string;
}): Layer<McpServerClient | McpServer, never, Protocol>

layerHttp

Added in v1.0.0 Source

Run the McpServer, using HTTP for input and output.

Signature

declare function layerHttp<I = Default>(options: {
  readonly name: string;
  readonly path: PathInput;
  readonly routerTag?: any;
  readonly version: string;
}): Layer<McpServerClient | McpServer>

Example

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)

layerHttpRouter

Added in v1.0.0 Source

Run the McpServer, using HTTP for input and output.

Uses a HttpLayerRouter to register the McpServer routes.

Signature

declare function layerHttpRouter(options: {
  readonly name: string;
  readonly path: PathInput;
  readonly version: string;
}): Layer<McpServerClient | McpServer, never, HttpRouter>

layerStdio

Added in v1.0.0 Source

Run the McpServer, using stdio for input and output.

Signature

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

Example

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)

McpServer

McpServer

Added in v1.0.0 Source

Signature

declare class McpServer extends any {
  constructor();
  static readonly layer: Layer<McpServerClient | McpServer>;
  static readonly make: Effect<any, unknown, unknown>;
}

Other

ResourceCompletions type

Added in v1.0.0 Source

Signature

type ResourceCompletions<Schemas extends ReadonlyArray<Schema.Schema.Any>> = { [K in Extract<keyof Schemas, `${number}`>]: (input: string) => Effect.Effect<Array<Schema.Schema.Type<Schemas[K]>>, any, any> }

ValidateCompletions type

Added in v1.0.0 Source

Signature

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

Prompts

prompt

Added in v1.0.0 Source

Register a prompt with the McpServer.

Signature

declare function prompt<E, R, Params = {}, ParamsI extends Record<string, string> = {}, ParamsR = never, Completions extends { [K in string | number | symbol]: (input: string) => Effect<Array<Params[K]>, any, any> } = {}>(options: {
  readonly completion?: ValidateCompletions<Completions, Extract<keyof Params, string>>;
  readonly content: (params: Params) => Effect<string | Array<{
    readonly content: unknown;
    readonly role: ["user", "assistant"];
  }>, E, R>;
  readonly description?: string;
  readonly name: string;
  readonly parameters?: any;
}): Layer<never, never, Exclude<R, McpServerClient> | Exclude<ParamsR, McpServerClient>>

registerPrompt

Added in v1.0.0 Source

Register a prompt with the McpServer.

Signature

declare function registerPrompt<E, R, Params = {}, ParamsI extends Record<string, string> = {}, ParamsR = never, Completions extends { [K in string | number | symbol]: (input: string) => Effect<Array<Params[K]>, any, any> } = {}>(options: {
  readonly completion?: ValidateCompletions<Completions, Extract<keyof Params, string>>;
  readonly content: (params: Params) => Effect<string | Array<{
    readonly content: unknown;
    readonly role: ["user", "assistant"];
  }>, E, R>;
  readonly description?: string;
  readonly name: string;
  readonly parameters?: any;
}): Effect<void, never, McpServer | Exclude<R, McpServerClient> | Exclude<ParamsR, McpServerClient>>

Resources

registerResource

Added in v1.0.0 Source

Register a resource with the McpServer.

Signature

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

resource

Added in v1.0.0 Source

Register a resource with the McpServer.

Signature

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

Tools

registerToolkit

Added in v1.0.0 Source

Register an AiToolkit with the McpServer.

Signature

declare const registerToolkit: <Tools extends Record<string, AiTool.Any>>(toolkit: Toolkit.Toolkit<Tools>) => Effect.Effect<void, never, McpServer | AiTool.HandlersFor<Tools> | Exclude<AiTool.Requirements<Tools>, McpServerClient>>

toolkit

Added in v1.0.0 Source

Register an AiToolkit with the McpServer.

Signature

declare function toolkit<Tools extends Record<string, Any>>(toolkit: Toolkit<Tools>): Layer<never, never, HandlersFor<Tools> | Exclude<Requirements<Tools>, McpServerClient>>