Server class

Main MCP Server class that handles all server-side protocol operations

Implemented types
Available extensions

Constructors

Server({required String name, required String version, String? description, String? instructions, ServerCapabilities capabilities = const ServerCapabilities()})
Creates a new MCP server with the specified parameters

Properties

capabilities → ServerCapabilities
Server capabilities configuration
final
defaultCacheMaxAge → Duration
Default cache duration
final
description → String?
Spec 2025-11-25: optional human-readable description of the server (Implementation.description). Emitted inside serverInfo on initialize when non-null.
final
hashCode → int
The hash code for this object.
no setterinherited
instructions → String?
Optional natural-language guidance about the server and its features (DiscoverResult.instructions on 2026-07-28). Surfaced by server/discover when set; the handshake initialize result does not carry it. Additive — null by default.
final
isAuthenticationEnabled → bool
Whether OAuth authentication is currently enabled.
no setter
isConnected → bool
Whether the server is currently connected
no setter
name → String
Name of the MCP server
final
onClientProgress ← void Function(String sessionId, Map<String, dynamic> params)?
no getter
onConnect → Stream<ClientSession>
Stream of session connection events
no setteroverride
onDisconnect → Stream<ClientSession>
Stream of session disconnection events
no setteroverride
onPromptsChanged → Stream<void>
Stream of prompts change events
no setter
onResourcesChanged → Stream<void>
Stream of resources change events
no setter
onResourceSubscribed → Stream<String>
Stream of resource subscription events (emits resource URI)
no setter
onResourceUnsubscribed → Stream<String>
Stream of resource unsubscription events (emits resource URI)
no setter
onToolsChanged → Stream<void>
Stream of tools change events
no setter
protectedResourceMetadata → Map<String, dynamic>?
Spec 2025-06-18 (RFC 9728): metadata for the server as an OAuth 2.0 Protected Resource. Returns null until configureProtectedResource has been called.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
supportedProtocolVersions → List<String>
Protocol versions this server implements
final
version → String
Version of the MCP server implementation
final

Methods

addCompletion({required String refType, required String refKey, required CompletionHandler handler}) → void
Register a completion handler for argument autocompletion (spec completion/complete).
addPrompt({required String name, required String description, required List<PromptArgument> arguments, required PromptHandler handler, String? title, List<Map<String, dynamic>>? icons, Map<String, dynamic>? meta}) → void
Add a prompt to the server
override
addPromptMap({required String name, required String description, required List<Map<String, dynamic>> arguments, required PromptHandler handler, String? title, List<Map<String, dynamic>>? icons, Map<String, dynamic>? meta}) → void
Map-based variant of addPrompt — accepts the prompt arguments as raw spec JSON ([{name, description, required?, default?}]). Sibling for adapters that hold the server as dynamic and so can't synthesise List<PromptArgument> at the call site.
addResource({required String uri, required String name, required String description, required String mimeType, Map<String, dynamic>? uriTemplate, required ResourceHandler handler, String? title, List<Map<String, dynamic>>? icons, Map<String, dynamic>? meta}) → void
Add a resource to the server
override
addResourceTemplate(ResourceTemplate template) → void
Add a resource template
addRoot(Root root) → void
Add a server-side root entry to the local cache.
addTool({required String name, required String description, required Map<String, dynamic> inputSchema, required ToolHandler handler, String? title, Map<String, dynamic>? outputSchema, List<Map<String, dynamic>>? icons, Map<String, dynamic>? meta}) → void
Add a tool to the server
override
addToolWithProgress(String name, String description, Map<String, dynamic> inputSchema, Future<CallToolResult> handler(Map<String, dynamic> arguments, {dynamic onProgress(double, String)?})) → void
Add a tool with progress support
cacheResource(String uri, ReadResourceResult content, [Duration? maxAge]) → void
Cache a resource
callTool(String name, Map<String, dynamic> arguments) → Future<CallToolResult>
Call a tool with the given arguments
callToolWithCancellation(String name, Map<String, dynamic> arguments, String operationId) → Future<CallToolResult>
Call a tool with cancellation support
cancelOperation(String operationId) → void
Cancel an operation
completeTask(String taskId, Map<String, dynamic> result) → Task?
Drive a task to completed with its terminal result.
configureMethodRateLimit(String method, RateLimitConfig config) → void
Configure rate limit for specific method
configureProtectedResource({required String resource, required List<String> authorizationServers, List<String>? scopesSupported, List<String>? bearerMethodsSupported, String? resourceDocumentation}) → void
Configure the OAuth Protected Resource metadata served at /.well-known/oauth-protected-resource (RFC 9728).
connect(ServerTransport transport) → void
Connect the server to a transport
createTask({String? statusMessage, int? ttlMs, int? pollIntervalMs}) → Task
Create a working task and store it. Returns the Task handle whose Task.toCreateTaskResult a tools/call (or other) handler can return so the client tracks it via tasks/get. Server-directed per the spec.
describe() → Map<String, dynamic>
Shared server-description assembly reused by the handshake initialize result and the stateless server/discover result (2026-07-28), so the two surfaces advertise the SAME serverInfo + capabilities object.
disableAuthentication() → void
Disable OAuth authentication.
disableRateLimiting() → void
Disable rate limiting
disconnect() → void
Disconnect the server from its transport
disconnectSession(String sessionId) → void
Disconnect a specific session
dispose() → void
Dispose server resources
enableAuthentication(TokenValidator validator, {List<String> publicPaths = const ['/health', '/ping'], List<String> defaultRequiredScopes = const [], bool strictMode = true}) → void
Enable OAuth authentication with the specified validator.
enableRateLimiting({RateLimitConfig? defaultConfig, Map<String, RateLimitConfig>? methodConfigs}) → void
Enable rate limiting with optional configuration
failTask(String taskId, Map<String, dynamic> error) → Task?
Drive a task to failed with a JSON-RPC error object.
getCachedResource(String uri) → CachedResource?
Get cached resource if available
getHealth() → ServerHealth
Get server health information
override
getMetrics() → Map<String, dynamic>
Get complete metrics
getPrompts() → List<Prompt>
Get all registered prompts
override
getRateLimitStats() → Map<String, dynamic>
Get rate limit statistics
getResources() → List<Resource>
Get all registered resources
override
getSessions() → List<ClientSession>
Get all active sessions
override
getTools() → List<Tool>
Get all registered tools
override
hasSession(String sessionId) → bool
Check if session exists
incrementMetric(String name, [int amount = 1]) → void
Increment metric counter
invalidateCache(String uri) → void
Invalidate cache for a resource
isOperationCancelled(String operationId) → bool
Check if operation is cancelled
isPathWithinRoots(String sessionId, String path) → bool
Check if a path is within client roots
listRoots() → List<Root>
Get all server roots
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyProgress(String operationId, double progress, String message) → void
Send progress notification for a tool operation
notifyResourceUpdated(String uri, {ResourceContent? content}) → void
Notify clients about a resource update
onTaskCancel(void fn(String operationId)) → void
onTaskInput(void fn(String taskId, dynamic inputResponses)) → void
Register hooks for task input delivery / cancellation (application logic that resumes or stops the task's work).
readResource(String uri) → Future<ReadResourceResult>
Read a resource by URI
registerOperation(String sessionId, String type) → PendingOperation
Register a pending operation for cancellation support
registerToolCall(String toolName, String sessionId, dynamic requestId, {Object? progressToken}) → String
Register a tool call and get an operation ID for progress/cancellation
removeCompletion({required String refType, required String refKey}) → void
Remove a completion handler.
removePrompt(String name) → void
Remove a prompt from the server
override
removeResource(String uri) → void
Remove a resource from the server
override
removeRoot(String uri) → void
Remove a server-side cached root entry (see addRoot for the direction caveat).
removeTool(String name) → void
Remove a tool from the server
override
requestClientElicitation(String sessionId, Map<String, dynamic> params, {Duration timeout = const Duration(seconds: 120)}) → Future<Map<String, dynamic>>
Server-initiated request: ask the connected client to elicit input from the user (spec 2025-06-18 elicitation/create).
requestClientRoots(String sessionId, {Duration timeout = const Duration(seconds: 30)}) → Future<List<Root>>
Server-initiated request: ask the connected client for its current list of filesystem / URI roots (spec roots/list).
requestClientSampling(String sessionId, Map<String, dynamic> params, {Duration timeout = const Duration(seconds: 60)}) → Future<Map<String, dynamic>>
Server-initiated request: ask the connected client's LLM to generate a completion (spec sampling/createMessage).
requireTaskInput(String taskId, Map<String, dynamic> inputRequests) → Task?
Move a task to input_required, surfacing server→client inputRequests.
sendLog(McpLogLevel level, String message, {String? logger, dynamic data}) → void
Send a logging notification to the client
sendProgressNotification(String sessionId, String progressToken, double progress, [double? total]) → void
Send progress notification to the client
startTimer(String name) → Stopwatch
Start timer for a metric
stopTimer(String name) → void
Stop timer for a metric
task(String taskId) → Task?
The current stored Task for taskId, or null.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited