DEV Community: MCP Dev Studio

Integrating AI with Flutter: Connecting Multiple LLM Providers to MCP Ecosystem

MCP Dev Studio — Thu, 01 May 2025 10:29:15 +0000

Originally published at GitHub

Introduction

Welcome to the fourth article in our "Integrating AI with Flutter" series, following our previous exploration of Creating AI Services with LlmServer and mcp_server. In today's rapidly evolving AI landscape, relying on a single language model provider is often insufficient for building robust, versatile applications. Different LLM providers excel in various tasks, and the Model Context Protocol (MCP) ecosystem offers a standardized way to interact with them all.

This article will guide you through integrating multiple LLM providers (OpenAI and Claude) with the MCP ecosystem in your Flutter applications, allowing you to leverage the unique strengths of each provider while maintaining a consistent developer experience.

Integration Patterns for Different LLM Providers
LlmCapability System and MCP Feature Mapping
Provider-Specific MCP Tool Implementations
Runtime Provider Switching
Building the MultiProviderManager
Smart Provider Selection
Creating a Multi-Provider User Interface
Next Steps

Integration Patterns for Different LLM Providers

When integrating multiple LLM providers with the MCP ecosystem, it's essential to understand their unique characteristics and the value they bring to your application.

Provider Characteristics

OpenAI (GPT Models)

Excellent at code generation and debugging
Well-implemented function calling capabilities
Broad domain knowledge across multiple fields

Anthropic (Claude Models)

Very long context window (up to 200K tokens)
Strong document analysis capabilities
Focus on safety and bias control

By integrating both these providers through the Model Context Protocol, you can create applications that select the optimal provider for each task while maintaining a consistent interface.

LlmCapability System and MCP Feature Mapping

The mcp_llm package provides an LlmCapability system that abstracts the capabilities of different LLM providers. This system plays a crucial role in mapping provider-specific features to standardized MCP tools.

Core Components of the LlmCapability System

class ProviderCapabilities {
  final bool supportsStreaming;
  final bool supportsToolCalls;
  final int maxContextLength;
  final Map<String, dynamic> specificCapabilities;

  ProviderCapabilities({
    required this.supportsStreaming,
    required this.supportsToolCalls,
    required this.maxContextLength,
    required this.specificCapabilities,
  });
}

This class represents the capabilities of an LLM provider and is used for MCP tool creation and feature enablement. The specificCapabilities map stores provider-specific features.

Implementation of Capability Assessment

// Assess provider capabilities
ProviderCapabilities _assessProviderCapabilities(String providerName) {
  final capabilities = ProviderCapabilities(
    supportsStreaming: true,
    supportsToolCalls: true,
    maxContextLength: _getMaxContextLength(providerName),
    specificCapabilities: {},
  );

  // Add provider-specific capabilities
  switch (providerName.toLowerCase()) {
    case 'openai':
      capabilities.specificCapabilities['vision'] = true;
      capabilities.specificCapabilities['functionCalling'] = true;
      capabilities.specificCapabilities['codeCompletion'] = true;
      break;
    case 'claude':
      capabilities.specificCapabilities['vision'] = true;
      capabilities.specificCapabilities['documentAnalysis'] = true;
      capabilities.specificCapabilities['longContext'] = true;
      break;
  }

  return capabilities;
}

This function evaluates the capabilities of a provider based on its name, which can then be used for MCP tool creation and provider selection.

Provider-Specific MCP Tool Implementations

Each LLM provider has differences in how they implement tool calling and features. For example, OpenAI uses 'function calling', while Claude has a more general tool calling mechanism. Here's how to handle these differences effectively:

Implementation of Chat Methods

// Send chat message to provider
Future<LlmResponse> chat(String provider, String message, {bool enableTools = true}) async {
  final client = _llmClients[provider];
  if (client == null) {
    throw Exception('Provider $provider not available');
  }

  try {
    _updateProviderStatus(provider, ProviderStatus.processing);

    final response = await client.chat(
      message,
      enableTools: enableTools,
    );

    _updateProviderStatus(provider, ProviderStatus.ready);
    return response;
  } catch (e) {
    _updateProviderStatus(provider, ProviderStatus.error, error: e.toString());
    rethrow;
  }
}

This method processes a chat message using the selected provider and updates the provider's status appropriately.

Handling Streaming Responses

// Stream chat responses
Stream<LlmResponseChunk> streamChat(String provider, String message, {bool enableTools = true}) {
  final client = _llmClients[provider];
  if (client == null) {
    throw Exception('Provider $provider not available');
  }

  try {
    _updateProviderStatus(provider, ProviderStatus.processing);

    final responseStream = client.streamChat(
      message,
      enableTools: enableTools,
    );

    // Transform stream to update status when complete
    final transformedStream = responseStream.transform(
        StreamTransformer<LlmResponseChunk, LlmResponseChunk>.fromHandlers(
            handleData: (data, sink) {
              sink.add(data);

              if (data.isDone == true) {
                _updateProviderStatus(provider, ProviderStatus.ready);
              }
            },
            handleError: (error, stackTrace, sink) {
              _updateProviderStatus(provider, ProviderStatus.error, error: error.toString());
              sink.addError(error, stackTrace);
            },
            handleDone: (sink) {
              _updateProviderStatus(provider, ProviderStatus.ready);
              sink.close();
            }
        )
    );

    return transformedStream;
  } catch (e) {
    _updateProviderStatus(provider, ProviderStatus.error, error: error.toString());
    rethrow;
  }
}

This method handles streaming responses and updates the provider status on completion or error.

Runtime Provider Switching

Maintaining MCP connections and context while switching between LLM providers is crucial. Here's how to implement this:

Setting Up the MCP Client

// Setup MCP client connection
Future<void> _setupMcpClient(String serverUrl, String? authToken) async {
  try {
    // Create MCP client instance
    _mcpClient = mcp.McpClient.createClient(
      name: 'multi_provider_app',
      version: '1.0.0',
      capabilities: const mcp.ClientCapabilities(
        roots: true,
        rootsListChanged: true,
        sampling: true,
      ),
    );

    // Create transport for MCP connection
    final headers = authToken != null && authToken.isNotEmpty
        ? {'Authorization': 'Bearer $authToken'}
        : null;

    final transport = await mcp.McpClient.createSseTransport(
      serverUrl: serverUrl,
      headers: headers,
    );

    // Setup connection state change event handler
    _mcpClient!.onNotification('connection_state_changed', (params) {
      _updateConnectionState();
    });

    // Connect to MCP server with retry
    await _mcpClient!.connectWithRetry(
      transport,
      maxRetries: 3,
      delay: const Duration(seconds: 2),
    );

    // Update initial connection state
    _updateConnectionState();
  } catch (e) {
    rethrow;
  }
}

This method sets up the MCP client and monitors connection state changes.

Executing Across Multiple Providers

// Execute query across multiple providers
Future<Map<String, LlmResponse>> executeAcrossProviders(
    String query,
    {
      List<String>? providers,
      bool enableTools = true,
    }
    ) async {
  final targetProviders = providers ?? _llmClients.keys.toList();

  final futures = <String, Future<LlmResponse>>{};
  for (final provider in targetProviders) {
    if (_llmClients.containsKey(provider)) {
      futures[provider] = chat(provider, query, enableTools: enableTools);
    }
  }

  final responses = <String, LlmResponse>{};
  for (final provider in futures.keys) {
    try {
      responses[provider] = await futures[provider]!;
    } catch (_) {
      // Continue with other providers even if one fails
    }
  }

  return responses;
}

This method allows you to execute the same query across multiple providers and compare the results.

Building the MultiProviderManager

To effectively manage multiple LLM providers, we've implemented a MultiProviderManager class. This class handles provider registration, status management, and request routing.

Class Structure

class MultiProviderManager {
  // Core components
  late McpLlm _mcpLlm;
  mcp.Client? _mcpClient;
  final Map<String, LlmClient> _llmClients = {};

  // State streams
  final _connectionStateController = StreamController<bool>.broadcast();
  final _providerStateController = StreamController<Map<String, ProviderStatus>>.broadcast();

  // Provider capabilities
  final Map<String, ProviderCapabilities> _providerCapabilities = {};

  // Public access to state streams
  Stream<bool> get connectionState => _connectionStateController.stream;
  Stream<Map<String, ProviderStatus>> get providerStatus => _providerStateController.stream;

  // Available providers
  List<String> get availableProviders => _llmClients.keys.toList();

  // Constructor
  MultiProviderManager() {
    _mcpLlm = McpLlm();
    _mcpLlm.registerProvider('openai', OpenAiProviderFactory());
    _mcpLlm.registerProvider('claude', ClaudeProviderFactory());
  }

  // Additional methods...
}

Initialization and Setup

// Setup MCP and LLM providers
Future<void> initialize({
  required String mcpServerUrl,
  String? mcpAuthToken,
  String? openaiApiKey,
  String? claudeApiKey,
}) async {
  try {
    // Setup MCP client
    await _setupMcpClient(mcpServerUrl, mcpAuthToken);

    // Setup OpenAI client if API key is provided
    if (openaiApiKey != null && openaiApiKey.isNotEmpty) {
      await _setupLlmClient('openai', openaiApiKey);
    }

    // Setup Claude client if API key is provided
    if (claudeApiKey != null && claudeApiKey.isNotEmpty) {
      await _setupLlmClient('claude', claudeApiKey);
    }

    // Update connection state
    _updateConnectionState();
  } catch (e) {
    rethrow;
  }
}

This method initializes the MCP client and sets up LLM clients for each provider with the provided API keys.

Setting Up LLM Clients for Different Providers

// Setup LLM client for a provider
Future<void> _setupLlmClient(String providerName, String apiKey) async {
  try {
    // Get default model for the provider
    final model = _getDefaultModel(providerName);

    // Create LLM client with MCP integration
    final llmClient = await _mcpLlm.createClient(
      providerName: providerName,
      config: LlmConfiguration(
        apiKey: apiKey,
        model: model,
        options: {
          'temperature': 0.7,
          'max_tokens': 1500,
        },
      ),
      mcpClient: _mcpClient,
      systemPrompt: 'You are a helpful assistant with access to various tools. Provide concise and accurate responses.',
    );

    // Store the client
    _llmClients[providerName] = llmClient;

    // Store provider capabilities
    _providerCapabilities[providerName] = _assessProviderCapabilities(providerName);

    // Update provider status
    _updateProviderStatus(providerName, ProviderStatus.ready);
  } catch (e) {
    _updateProviderStatus(providerName, ProviderStatus.error, error: e.toString());
  }
}

This method sets up an LLM client for a specific provider and assesses its capabilities.

Smart Provider Selection

Implementing smart routing to automatically select the most appropriate LLM provider based on the query content is a powerful feature:

Provider Selection Logic

// Select best provider for a query
String selectProviderForQuery(String query, {Set<String>? requiredCapabilities}) {
  if (_llmClients.isEmpty) {
    throw Exception('No LLM clients available');
  }

  // Code-related queries
  if (query.toLowerCase().contains('code') ||
      query.toLowerCase().contains('programming') ||
      query.toLowerCase().contains('function')) {
    if (_llmClients.containsKey('openai')) {
      return 'openai';
    }
  }

  // Creative content
  if (query.toLowerCase().contains('story') ||
      query.toLowerCase().contains('creative') ||
      query.toLowerCase().contains('write a')) {
    if (_llmClients.containsKey('claude')) {
      return 'claude';
    }
  }

  // Check for required capabilities
  if (requiredCapabilities != null && requiredCapabilities.isNotEmpty) {
    for (final provider in _llmClients.keys) {
      final capabilities = _providerCapabilities[provider];
      if (capabilities == null) continue;

      bool hasAllCapabilities = true;
      for (final capability in requiredCapabilities) {
        if (capabilities.specificCapabilities[capability] != true) {
          hasAllCapabilities = false;
          break;
        }
      }

      if (hasAllCapabilities) {
        return provider;
      }
    }
  }

  // Default to ready provider from current status
  for (final provider in _llmClients.keys) {
    if (_providerStatus[provider] == ProviderStatus.ready) {
      return provider;
    }
  }

  // Fallback to first provider
  return _llmClients.keys.first;
}

This method analyzes the query content and required capabilities to select the optimal provider.

Smart Execution Implementation

// Auto-select provider and execute query
Future<ProviderResponse> smartExecute(
    String query,
    {
      Set<String>? requiredCapabilities,
      bool enableTools = true,
    }
    ) async {
  final provider = selectProviderForQuery(query, requiredCapabilities: requiredCapabilities);

  try {
    final response = await chat(provider, query, enableTools: enableTools);
    return ProviderResponse(
      provider: provider,
      response: response,
      error: null,
    );
  } catch (e) {
    return ProviderResponse(
      provider: provider,
      response: null,
      error: e.toString(),
    );
  }
}

This method automatically selects the best provider and executes the query.

Creating a Multi-Provider User Interface

Let's implement a UI that integrates multiple LLM providers, allowing users to select providers, compare responses, and view real-time status:

Multi-Provider Chat Screen

class MultiProviderChatScreen extends StatefulWidget {
  const MultiProviderChatScreen({Key? key}) : super(key: key);

  @override
  State<MultiProviderChatScreen> createState() => _MultiProviderChatScreenState();
}

class _MultiProviderChatScreenState extends State<MultiProviderChatScreen> {
  final TextEditingController _textController = TextEditingController();
  final List<ChatMessage> _messages = [];

  late MultiProviderManager _providerManager;
  String _selectedProvider = '';
  bool _isLoading = true;
  bool _isStreaming = false;
  bool _mcpConnected = false;
  Map<String, ProviderStatus> _providerStatus = {};

  @override
  void initState() {
    super.initState();
    logger.debug('Initializing chat screen');
    _initialize();
  }

  // Initialize the manager
  Future<void> _initialize() async {
    try {
      // Manager setup and initialization
      // ...
    } catch (e) {
      // Error handling
      // ...
    }
  }

  // Handle message sending
  void _sendMessage(String text) async {
    if (text.trim().isEmpty) return;

    // Various message handling methods
    // ...
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Multi-Provider AI Chat'),
        actions: [
          // Provider selector dropdown
          // ...
          // MCP connection status indicator
          // ...
        ],
      ),
      body: Column(
        children: [
          // Message list
          // ...
          // Progress indicator
          // ...
          // Text input
          // ...
        ],
      ),
    );
  }
}

This screen interacts with multiple LLM providers, displays status visually, and handles various commands.

Provider Status Display

// Provider selector
DropdownButton<String>(
  value: _selectedProvider.isEmpty ? null : _selectedProvider,
  hint: const Text('Select Provider'),
  onChanged: (String? newValue) {
    if (newValue != null) {
      logger.info('User selected provider: $newValue');
      setState(() {
        _selectedProvider = newValue;
      });
    }
  },
  items: _providerManager.availableProviders
      .map<DropdownMenuItem<String>>((String value) {
    // Show provider status with icon
    IconData iconData;
    Color iconColor;

    switch (_providerStatus[value]) {
      case ProviderStatus.ready:
        iconData = Icons.check_circle;
        iconColor = Colors.green;
        break;
      case ProviderStatus.processing:
        iconData = Icons.hourglass_top;
        iconColor = Colors.orange;
        break;
      case ProviderStatus.error:
        iconData = Icons.error;
        iconColor = Colors.red;
        break;
      case ProviderStatus.initializing:
        iconData = Icons.pending;
        iconColor = Colors.blue;
        break;
      case ProviderStatus.unknown:
      default:
        iconData = Icons.help;
        iconColor = Colors.grey;
        break;
    }

    return DropdownMenuItem<String>(
      value: value,
      child: Row(
        mainAxisSize: MainAxisSize.min,
        children: [
          Icon(iconData, color: iconColor, size: 16),
          const SizedBox(width: 8),
          Text(value),
        ],
      ),
    );
  }).toList(),
),

This dropdown displays the list of available providers and their current status with visual indicators.

Command Handling

The UI handles special commands:

/provider [name]: Switch to a specific provider
/compare [query]: Execute the same query across multiple providers and compare results
/stream [query]: Enable streaming responses
/smart [query]: Auto-select provider and execute

Use Cases and Examples

Let's explore some example use cases for the MultiProviderManager:

1. Provider Comparison

// Compare providers
void _compareProviders(String text) async {
  try {
    setState(() {
      _isLoading = true;
      _messages.add(ChatMessage(
        text: 'Comparing providers...',
        isUser: false,
      ));
    });

    final responses = await _providerManager.executeAcrossProviders(text);

    // Create comparison message
    final sb = StringBuffer('Comparison results:\n\n');

    for (final provider in responses.keys) {
      sb.writeln('--- $provider ---');
      sb.writeln(responses[provider]!.text);
      sb.writeln();
    }

    setState(() {
      _isLoading = false;
      // Replace "comparing" message with results
      _messages.last = ChatMessage(
        text: sb.toString(),
        isUser: false,
        isComparison: true,
      );
    });
  } catch (e) {
    // Error handling
  }
}

2. Smart Provider Selection

// Auto-select best provider and execute
void _smartExecute(String text) async {
  try {
    setState(() {
      _isLoading = true;
    });

    final result = await _providerManager.smartExecute(text);

    setState(() {
      _isLoading = false;

      if (result.isSuccess) {
        _messages.add(ChatMessage(
          text: result.response!.text,
          isUser: false,
          providerName: result.provider,
          toolCalls: result.response!.toolCalls,
          isAutoSelected: true,
        ));
      } else {
        _messages.add(ChatMessage(
          text: 'Error with provider ${result.provider}: ${result.error}',
          isUser: false,
          isError: true,
        ));
      }
    });
  } catch (e) {
    // Error handling
  }
}

Next Steps

In this article, we've explored integrating multiple LLM providers with the MCP ecosystem. Building on this foundation, you can explore these advanced topics:

Extending MCP Ecosystem with Plugins: Develop custom tools and resources as plugins
Building and Managing Multi-MCP Environments: Design distributed environments with multiple MCP clients/servers
Parallel Processing in MCP-LLM Integration: Implement parallel task execution with MCP tools
Building RAG Systems with MCP Integration: Create knowledge-based systems with document retrieval

Conclusion

Integrating multiple LLM providers with the MCP ecosystem allows you to leverage the strengths of each provider while maintaining a consistent development experience. Using the MultiProviderManager class, you can effectively manage multiple providers, select the optimal provider based on the query content, and maintain MCP connections during provider switches.

By implementing these patterns in your Flutter application, you can deliver diverse AI capabilities while managing code complexity. The Model Context Protocol serves as the cornerstone of this integration, providing a standardized interface across different providers.

In the next article, we'll explore building and extending the MCP plugin system to further enhance your AI applications.

Resources

Support the Developer

If you found this article helpful, please consider supporting the development of more free content through Patreon. Your support makes a big difference!

Tags: #Flutter #AI #MCP #LLM #Dart #OpenAI #Claude #ModelContextProtocol #AIIntegration #MultiProvider

Integrating AI with Flutter: Creating AI Services with LlmServer and mcp_server

MCP Dev Studio — Thu, 01 May 2025 08:43:14 +0000

Originally published at GitHub

Introduction

In our ongoing series about integrating AI with Flutter applications, we previously explored client-side integration with LlmClient and mcp_client. Now, it's time to dive into the server-side integration using LlmServer and mcp_server. This powerful combination allows you to provide AI capabilities as services that can be consumed by multiple clients.

This article—the fifth in our Model Context Protocol (MCP) series and the third focused on mcp_llm—explores how to build robust AI services that leverage the standardized MCP protocol, making your AI capabilities accessible to a wide range of client applications.

Understanding LlmServer and mcp_server
Server-Side Integration Architecture
Setting Up the Integration
Registering LLM Functions as MCP Tools
Core LLM Plugins
AI-Based Tool Generation
Server Monitoring and Management
Next Steps

Understanding LlmServer and mcp_server

Before we dive into the integration, let's clarify the roles of these two key components:

The Role of LlmServer

LlmServer is a core component from the mcp_llm package that serves as the server-side implementation for AI capabilities. It's responsible for:

Communicating with Large Language Models (LLMs) like Claude, GPT, etc.
Registering and managing AI-powered tools
Processing queries and generating responses
Managing plugins and extensions
Monitoring performance and requests

It essentially exposes AI capabilities as a service, rather than embedding them directly in your client applications.

The Role of mcp_server

mcp_server implements the Model Context Protocol (MCP) on the server side, allowing:

Registration and exposure of tools to clients
Management of resources (databases, APIs, files)
Provision of standardized prompt templates
Client connection and session management
Protocol-based communication

The Value of Integration

When integrated, these components enable:

Exposing LLM capabilities as standardized MCP tools
Centralizing AI functions for multiple clients
Managing API keys and credentials securely in one place
Dynamically generating new tools based on natural language descriptions
Scaling AI capabilities independently from client applications

This integration transforms AI development by creating a clear separation between the client interface and the backend AI processing, allowing for better scalability, security, and resource management.

Server-Side Integration Architecture

Understanding the architecture of this integration is crucial for implementation:

Integration Model

[Client Apps] ← HTTP/SSE → [mcp_server] ↔ [LlmServer] ← HTTP → [LLM API]
                                ↓              ↓
                        [Tools/Resources]  [Plugin Management]

Communication Flow

The communication flow between components follows this pattern:

mcp_server receives requests from clients (Flutter apps, web clients, etc.)
If the request involves an LLM tool, it's forwarded to LlmServer
LlmServer processes the request and communicates with the LLM provider
The LLM's response is returned to LlmServer
LlmServer processes the response and returns the result to mcp_server
mcp_server sends the final result back to the client

This layered architecture creates clear separation of concerns and enables efficient scaling.

Setting Up the Integration

Let's walk through the process of setting up an integrated AI server using LlmServer and mcp_server:

import 'dart:async';
import 'dart:io';
import 'package:mcp_llm/mcp_llm.dart';
import 'package:mcp_server/mcp_server.dart' as mcp;
import 'package:dotenv/dotenv.dart';

Future<void> main() async {
  // Logger setup - utility for structured server logs
  final logger = Logger.getLogger('mcp_llm.server');

  try {
    // Load environment variables - server configuration settings
    final env = DotEnv()..load();
    final apiKey = env['OPENAI_API_KEY'] ?? '';
    final serverPort = int.tryParse(env['MCP_SERVER_PORT'] ?? '8999') ?? 8999;
    final authToken = env['MCP_AUTH_TOKEN'] ?? 'test_token';
    final logLevelStr = env['LOG_LEVEL'] ?? 'info';

    // Set log level - various levels of detail for logging
    final LogLevel logLevel;
    switch (logLevelStr.toLowerCase()) {
      case 'trace': logLevel = LogLevel.trace; break;
      case 'debug': logLevel = LogLevel.debug; break;
      case 'info': logLevel = LogLevel.info; break;
      case 'warning': logLevel = LogLevel.warning; break;
      case 'error': logLevel = LogLevel.error; break;
      default: logLevel = LogLevel.info;
    }
    logger.setLevel(logLevel);

    // Verify API key - required setting for server startup
    if (apiKey.isEmpty) {
      logger.error('OPENAI_API_KEY is not set.');
      exit(1);
    }

    logger.info('Starting AI service server...');

    // Create McpLlm instance - entry point for all LLM functionality
    final mcpLlm = McpLlm();

    // Register LLM provider - support for various AI models
    mcpLlm.registerProvider('openai', OpenAiProviderFactory());
    logger.debug('OpenAI provider registered.');

    // Create MCP server - Model Context Protocol server configuration
    final mcpServer = mcp.McpServer.createServer(
      name: 'ai_service',
      version: '1.0.0',
      capabilities: mcp.ServerCapabilities(
        tools: true,
        toolsListChanged: true,
        resources: true,
        resourcesListChanged: true,
        prompts: true,
        promptsListChanged: true,
        sampling: true,
      ),
    );

    // Register custom tools - add specific functionality tools
    final pluginManager = PluginManager();

    await pluginManager.registerPlugin(EchoToolPlugin());
    await pluginManager.registerPlugin(CalculatorToolPlugin());

    // Create LlmServer - server for providing AI functionality as a service
    final llmServer = await mcpLlm.createServer(
      providerName: 'openai',  // LLM provider to use
      config: LlmConfiguration(
        apiKey: apiKey,
        model: 'gpt-4o',  // Model to use
        options: {
          'temperature': 0.3,  // Control response randomness/creativity (0-1)
          'max_tokens': 2000,  // Maximum output token limit
        },
      ),
      storageManager: MemoryStorage(),
      pluginManager: pluginManager,
      mcpServer: mcpServer,  // MCP server integration
    );

    logger.info('LlmServer has been created.');

    // Register core LLM plugins - enable basic AI functionality
    await llmServer.registerCoreLlmPlugins(
      registerCompletionTool: true,  // Text generation tool
      registerStreamingTool: true,   // Streaming response tool
      registerEmbeddingTool: true,   // Embedding generation tool
      registerRetrievalTools: true,  // Retrieval-related tools
      registerWithServer: true,      // Auto-register with MCP server
    );
    logger.info('Core LLM plugins registered.');

    // Add auto-generated tool - LLM designs/implements tool automatically
    // Executing asynchronously to avoid delaying server startup
    _generateAutomaticTool(llmServer, logger);

    // Create SSE transport - communication channel between server and clients
    final transport = mcp.McpServer.createSseTransport(
      endpoint: '/sse',
      messagesEndpoint: '/message',
      port: serverPort,
      authToken: authToken,  // Token for client authentication
    );

    // Connect MCP server with transport
    mcpServer.connect(transport);
    logger.info('MCP server connected to transport.');

    // Output server information
    logger.info('AI service running on port $serverPort.');
    logger.info('Server URL: http://localhost:$serverPort/sse');

    // Verify auth token setting
    if (authToken.isNotEmpty) {
      logger.debug('Auth token set: $authToken');
    }

    // Output available tools
    final tools = mcpServer.getTools();
    logger.info('');
    logger.info('Available tools:');
    for (final tool in tools) {
      logger.info('- ${tool.name}: ${tool.description}');
    }

    // Handle server shutdown - for Ctrl+C or other termination
    ProcessSignal.sigint.watch().listen((_) async {
      logger.info('Shutting down server...');
      await mcpLlm.shutdown();
      exit(0);
    });

    // Maintain event loop - keep server running
    try {
      logger.info('Server ready to process requests. Press Ctrl+C to shut down.');
      await Future.delayed(Duration(days: 365));
    } catch (e) {
      logger.error('Error during server execution: $e');
    }

  } catch (e, stack) {
    logger.error('Error during server startup: $e');
    logger.debug('Stack trace: $stack');
    exit(1);
  }
}

// AI-based tool generation function - LLM designs and implements tools automatically
void _generateAutomaticTool(LlmServer server, Logger logger) async {
  try {
    logger.info('Generating sentiment analysis tool...');

    // Tool description - LLM uses this description to generate the tool
    final toolDescription = """
      Create a tool that analyzes the sentiment of text. This tool should provide:

      1. Sentiment analysis of input text (positive, negative, neutral)
      2. Sentiment score (-1.0 to 1.0, where -1 is most negative, 1 is most positive)
      3. Extraction of key sentiment words
      4. Analysis confidence (0.0 to 1.0)

      It should support text in multiple languages and provide results in either text or JSON format.

      The tool name must be sentiment_analyzer.
      """;

    // Attempt LLM-based tool generation
    try {
      logger.info('Attempting LLM-based tool generation...');

      // Generate tool
      final success = await server.generateAndRegisterTool(
        toolDescription,
        registerWithServer: true,  // Auto-register with server
      );

      logger.info('Automatic tool generation result: ${success ? "Success" : "Failed"}');

      if (!success) {
        logger.info('Automatic generation failed...');
      }
    } catch (e) {
      logger.error('Error during tool generation: $e');

      // Handle error if direct registration is needed
      logger.info('Error...');
    }
  } catch (e) {
    logger.error('Error during sentiment analyzer tool setup: $e');
  }
}

class EchoToolPlugin extends BaseToolPlugin {
  EchoToolPlugin() : super(
    name: 'echo',
    version: '1.0.0',
    description: 'Echoes back the input message with optional transformation',
    inputSchema: {
      'type': 'object',
      'properties': {
        'message': {
          'type': 'string',
          'description': 'Message to echo back'
        },
        'uppercase': {
          'type': 'boolean',
          'description': 'Whether to convert to uppercase',
          'default': false
        }
      },
      'required': ['message']
    },
  );

  @override
  Future<LlmCallToolResult> onExecute(Map<String, dynamic> arguments) async {
    final message = arguments['message'] as String;
    final uppercase = arguments['uppercase'] as bool? ?? false;

    final result = uppercase ? message.toUpperCase() : message;

    Logger.getLogger('LlmServerDemo').debug(message);
    return LlmCallToolResult([
      LlmTextContent(text: result),
    ]);
  }
}

class CalculatorToolPlugin extends BaseToolPlugin {
  CalculatorToolPlugin() : super(
    name: 'calculator',
    version: '1.0.0',
    description: 'Performs basic arithmetic operations',
    inputSchema: {
      'type': 'object',
      'properties': {
        'operation': {
          'type': 'string',
          'description': 'The operation to perform (add, subtract, multiply, divide)',
          'enum': ['add', 'subtract', 'multiply', 'divide']
        },
        'a': {
          'type': 'number',
          'description': 'First number'
        },
        'b': {
          'type': 'number',
          'description': 'Second number'
        }
      },
      'required': ['operation', 'a', 'b']
    },
  );

  @override
  Future<LlmCallToolResult> onExecute(Map<String, dynamic> arguments) async {
    final operation = arguments['operation'] as String;
    final a = (arguments['a'] as num).toDouble();
    final b = (arguments['b'] as num).toDouble();

    double result;
    switch (operation) {
      case 'add':
        result = a + b;
        break;
      case 'subtract':
        result = a - b;
        break;
      case 'multiply':
        result = a * b;
        break;
      case 'divide':
        if (b == 0) {
          throw Exception('Division by zero');
        }
        result = a / b;
        break;
      default:
        throw Exception('Unknown operation: $operation');
    }

    Logger.getLogger('LlmServerDemo').debug('$result');
    return LlmCallToolResult([
      LlmTextContent(text: result.toString()),
    ]);
  }
}

The code above sets up an integrated AI server with several key components:

Environment configuration: Loading API keys, port settings, and authentication tokens from environment variables
McpLlm and provider setup: Creating the main instance and registering LLM providers
MCP server creation: Setting up the MCP server with required capabilities
Tool registration: Registering basic tools like Echo and Calculator
LlmServer creation: Creating the LLM server and connecting it to the MCP server
Core plugin registration: Registering basic AI functionality as tools
AI-based tool generation: Using the LLM to generate a sentiment analysis tool automatically
Transport setup: Setting up SSE transport for client communication

Registering LLM Functions as MCP Tools

One of the key aspects of this integration is exposing LLM functionality as MCP tools that clients can access. The provided code demonstrates two approaches to tool registration:

1. Plugin Registration

The sample code shows how to create tool plugins by extending the BaseToolPlugin class and registering them via the PluginManager:

// Register custom tools through PluginManager
final pluginManager = PluginManager();
await pluginManager.registerPlugin(EchoToolPlugin());
await pluginManager.registerPlugin(CalculatorToolPlugin());

The EchoToolPlugin and CalculatorToolPlugin classes demonstrate how to implement custom tools by:

Defining the tool name, version, and description
Specifying the input schema as JSON Schema
Implementing the onExecute method to handle tool calls

2. Core LLM Plugins

The registerCoreLlmPlugins method automatically registers a set of core LLM capabilities as tools:

// Register core LLM plugins
await llmServer.registerCoreLlmPlugins(
  registerCompletionTool: true,  // Text generation
  registerStreamingTool: true,   // Streaming responses
  registerEmbeddingTool: true,   // Embedding generation
  registerRetrievalTools: true,  // Retrieval-related tools
  registerWithServer: true,      // Auto-register with MCP server
);

These core plugins expose the fundamental LLM capabilities (text generation, embeddings, etc.) as standardized tools, making them available to clients through the MCP protocol.

Core LLM Plugins

The core LLM plugins registered through registerCoreLlmPlugins provide access to the following functionalities:

CompletionTool: Enables text generation from prompts
StreamingTool: Provides streaming responses for real-time updates
EmbeddingTool: Generates vector embeddings for text
RetrievalTools: Offers retrieval-augmented generation capabilities

These tools are automatically registered with the MCP server, making them available to all connected clients.

AI-Based Tool Generation

One of the most innovative features demonstrated in the code is the ability to generate new tools automatically using the LLM itself. This is implemented in the _generateAutomaticTool function:

void _generateAutomaticTool(LlmServer server, Logger logger) async {
  try {
    logger.info('Generating sentiment analysis tool...');

    // Tool description - LLM uses this description to generate the tool
    final toolDescription = """
      Create a tool that analyzes the sentiment of text. This tool should provide:

      1. Sentiment analysis of input text (positive, negative, neutral)
      2. Sentiment score (-1.0 to 1.0, where -1 is most negative, 1 is most positive)
      3. Extraction of key sentiment words
      4. Analysis confidence (0.0 to 1.0)

      It should support text in multiple languages and provide results in either text or JSON format.

      The tool name must be sentiment_analyzer.
      """;

    // Attempt LLM-based tool generation
    try {
      logger.info('Attempting LLM-based tool generation...');

      // Generate tool
      final success = await server.generateAndRegisterTool(
        toolDescription,
        registerWithServer: true,  // Auto-register with server
      );

      logger.info('Automatic tool generation result: ${success ? "Success" : "Failed"}');

      if (!success) {
        logger.info('Automatic generation failed...');
      }
    } catch (e) {
      logger.error('Error during tool generation: $e');
      logger.info('Error...');
    }
  } catch (e) {
    logger.error('Error during sentiment analyzer tool setup: $e');
  }
}

This function uses the generateAndRegisterTool method to:

Send a natural language tool description to the LLM
Have the LLM design the tool's input schema and implementation
Generate executable code for the tool functionality
Register the resulting tool with the server

This powerful capability allows developers to create complex tools simply by describing them in natural language, greatly accelerating development.

Server Monitoring and Management

The sample code includes several features for effective server monitoring and management:

1. Logging System

The code sets up a comprehensive logging system with different levels:

final logger = Logger.getLogger('mcp_llm.server');

// Set log level based on environment
final LogLevel logLevel;
switch (logLevelStr.toLowerCase()) {
  case 'trace': logLevel = LogLevel.trace; break;
  case 'debug': logLevel = LogLevel.debug; break;
  case 'info': logLevel = LogLevel.info; break;
  case 'warning': logLevel = LogLevel.warning; break;
  case 'error': logLevel = LogLevel.error; break;
  default: logLevel = LogLevel.info;
}
logger.setLevel(logLevel);

This logging system helps track server operations, errors, and important events.

2. Tool Inventory

The code lists all available tools after registration:

// Output available tools
final tools = mcpServer.getTools();
logger.info('');
logger.info('Available tools:');
for (final tool in tools) {
  logger.info('- ${tool.name}: ${tool.description}');
}

This provides a clear view of what capabilities are available to clients.

3. Graceful Shutdown

The code implements a graceful shutdown mechanism to ensure proper resource cleanup:

// Handle server shutdown - for Ctrl+C or other termination
ProcessSignal.sigint.watch().listen((_) async {
  logger.info('Shutting down server...');
  await mcpLlm.shutdown();
  exit(0);
});

This ensures that all resources are properly released when the server is terminated.

Next Steps

After implementing the basic integration between LlmServer and mcp_server, there are several advanced topics you might want to explore:

Multiple LLM Provider Integration: Integrating different AI models (Claude, GPT, etc.) with MCP ecosystem
MCP Plugin System Development: Building custom tools and resources as plugins
Distributed MCP Environments: Creating complex systems with multiple MCP clients and servers
Parallel Processing with MCP Tools: Implementing parallel task execution with MCP tools
Building MCP-based RAG Systems: Implementing knowledge-based systems with document retrieval

The integration of LlmServer with mcp_server opens up numerous possibilities for building AI-powered services that can be consumed by a wide range of client applications.

Conclusion

In this article, we've explored the integration between LlmServer and mcp_server to create powerful AI services. This server-side integration offers numerous benefits:

Standardized API: Expose AI capabilities through a standardized protocol
Resource Optimization: Process heavy AI workloads on the server, preserving client resources
Centralized Management: Manage all AI features and tools from a central location
Scalability: Easily add new AI features or tools without client-side changes
Multi-Client Support: Support various client platforms with a single server
Enhanced Security: Keep sensitive API keys and credentials on the server

The ability to automatically generate new tools using the LLM itself is particularly exciting, as it allows developers to create complex AI-powered tools using natural language descriptions instead of writing code.

By combining the client-side integration discussed in previous articles with the server-side integration presented here, you can build a complete, scalable AI ecosystem that leverages the power of the Model Context Protocol.

Resources

Support the Developer

If you found this article helpful, please consider supporting the development of more free content through Patreon. Your support makes a big difference!

Tags: #Flutter #AI #MCP #LLM #Dart #OpenAI #ModelContextProtocol #AIIntegration #mcp_server #LlmServer

Integrating AI with Flutter: Building Powerful Apps with LlmClient and mcp_client

MCP Dev Studio — Thu, 01 May 2025 08:05:39 +0000

Originally published at GitHub

Introduction

In our ongoing series about integrating AI with Flutter applications, we previously introduced the mcp_llm package as a comprehensive toolkit for connecting Large Language Models with Flutter apps. This article—the fourth in our Model Context Protocol (MCP) series and the second focused on mcp_llm—dives deeper into the integration between LlmClient and mcp_client, exploring how this powerful combination enables AI models to access external tools and resources.

The synergy between these components transforms AI capabilities from simple text generation to genuinely interactive and functional features that can interact with the real world. Let's explore how to build AI-powered applications with these components.

Understanding LlmClient and mcp_client
Integration Architecture
Setting Up the Integration
Leveraging MCP Tools
Working with MCP Resources
Managing Multiple MCP Clients
Implementing a Sample App
Next Steps

Understanding LlmClient and mcp_client

Before diving into integration details, let's clarify the roles of these two key components:

The Role of LlmClient

LlmClient is a core component from the mcp_llm package responsible for:

Communicating with Large Language Models (LLMs) like Claude, GPT, etc.
Managing chat sessions and contexts
Processing tool calls from the LLM
Handling streaming responses
Managing system prompts and parameters

It essentially serves as your app's gateway to AI capabilities.

The Role of mcp_client

mcp_client implements the Model Context Protocol (MCP) on the client side, allowing:

Communication with MCP servers
Access to external tools
Access to resources (databases, APIs, files)
Access to standardized prompt templates
Management of authentication and connections

The Value of Integration

When integrated, these components enable:

LLMs to call external tools and utilize results
Access to external data sources and APIs
Use of standardized prompt templates
Complex tool-based workflows
Bi-directional communication between AI and external systems

This integration transforms AI applications from simple chat interfaces to functional tools that can perform real-world actions based on user requests.

Integration Architecture

Understanding the architecture of this integration is crucial for implementation:

Integration Model

┌────────────────┐       ┌────────────────┐
│   LlmClient    │◄─────►│   mcp_client   │
└───────┬────────┘       └───────┬────────┘
        │                        │
        ▼                        ▼
┌────────────────┐       ┌────────────────┐
│  LLM Provider  │       │   MCP Server   │
│  (Claude, GPT) │       │  (Tools, etc.) │
└────────────────┘       └────────────────┘

Communication Flow

The communication flow between components follows this pattern:

LlmClient sends user queries to the LLM provider
If the LLM determines a tool is needed, it returns a tool call request
LlmClient forwards the tool call to mcp_client
mcp_client executes the tool via the MCP server
Tool results are returned to mcp_client
LlmClient passes tool results back to the LLM
The LLM generates a final response based on tool results

This architecture enables a seamless flow from user input to intelligent, tool-augmented AI responses.

Setting Up the Integration

Let's walk through the setup process for integrating LlmClient with mcp_client:

Project Setup

Start by creating a new Flutter project and adding the required dependencies:

# Create a new Flutter project
flutter create mcp_llm_client_integration

# Navigate to the project directory
cd mcp_llm_client_integration

# Add necessary packages
flutter pub add mcp_llm
flutter pub add mcp_client
flutter pub add flutter_dotenv

Create a .env file in your project root for configuration:

CLAUDE_API_KEY=your-claude-api-key
MCP_SERVER_URL=http://localhost:8999/sse
MCP_AUTH_TOKEN=your-auth-token

Update your pubspec.yaml to include the .env file as an asset:

flutter:
  assets:
    - .env
    # Other assets...

Basic Integration Setup

Here's how to set up the basic integration between LlmClient and mcp_client:

import 'package:mcp_llm/mcp_llm.dart';
import 'package:mcp_client/mcp_client.dart' as mcp;

Future<void> setupIntegration() async {
  // Create McpLlm instance
  final mcpLlm = McpLlm();

  // Register LLM provider
  mcpLlm.registerProvider('claude', ClaudeProviderFactory());

  // Create MCP client
  final mcpClient = mcp.McpClient.createClient(
    name: 'flutter_app',
    version: '1.0.0',
    capabilities: mcp.ClientCapabilities(
      roots: true,
      rootsListChanged: true,
      sampling: true,
    ),
  );

  // Create transport
  final transport = await mcp.McpClient.createSseTransport(
    serverUrl: 'http://localhost:8999/sse',
    headers: {'Authorization': 'Bearer your_token'},
  );

  // Connect to MCP server
  await mcpClient.connectWithRetry(
    transport,
    maxRetries: 3,
    delay: const Duration(seconds: 2),
  );

  // Create LlmClient with MCP client integration
  final llmClient = await mcpLlm.createClient(
    providerName: 'claude',
    config: LlmConfiguration(
      apiKey: 'your-claude-api-key',
      model: 'claude-3-haiku-20240307',
    ),
    mcpClient: mcpClient,  // Connect MCP client
    systemPrompt: 'You are a helpful assistant with access to various tools.',
  );

  // Now you can use llmClient to interact with AI and tools
}

Monitoring Connection State

It's important to monitor the connection state of your MCP client:

mcpClient.onNotification('connection_state_changed', (params) {
  final state = params['state'] as String;
  print('MCP connection state: $state');
  // Update UI or take action based on state changes
});

Leveraging MCP Tools

One of the most powerful aspects of this integration is the ability to use external tools through MCP. Here's how to leverage them:

Listing Available Tools

Future<void> listAvailableTools() async {
  final tools = await mcpClient.listTools();

  print('Available tools:');
  for (final tool in tools) {
    print('- ${tool.name}: ${tool.description}');
  }
}

Indirect Tool Calls via AI

Set up your AI to call tools when needed:

Future<void> chatWithToolUse() async {
  final response = await llmClient.chat(
    "What's the weather in New York today?", 
    enableTools: true,  // Enable tool usage
  );

  print('AI Response: ${response.text}');
}

Direct Tool Calls

You can also directly call tools:

Future<void> executeToolDirectly() async {
  try {
    final result = await llmClient.executeTool(
      'weather',  // Tool name
      {
        'location': 'New York',
        'unit': 'celsius',
      },
    );

    print('Tool execution result: $result');
  } catch (e) {
    print('Tool execution error: $e');
  }
}

Handling Tool Calls in Streaming Responses

Process tool calls while streaming responses:

Future<void> streamChatWithToolUse() async {
  final responseStream = llmClient.streamChat(
    "Tell me the weather in New York and San Francisco",
    enableTools: true,
  );

  final StringBuffer currentResponse = StringBuffer();

  await for (final chunk in responseStream) {
    // Handle text chunks
    if (chunk['textChunk'] != null && chunk['textChunk'].isNotEmpty) {
      currentResponse.write(chunk['textChunk']);
      print('Current response: ${currentResponse.toString()}');
    }

    // Check for stream completion
    if (chunk['isDone'] == true) {
      print('Response stream completed');
    }
  }
}

Working with MCP Resources

MCP resources provide structured access to external data and systems:

Listing Available Resources

Future<void> listAvailableResources() async {
  final resources = await mcpClient.listResources();

  print('Available resources:');
  for (final resource in resources) {
    print('- ${resource.name}: ${resource.description}');
    print('  URI: ${resource.uri}');
  }
}

Reading Resources

Future<void> readResource() async {
  try {
    final resourceContent = await mcpClient.readResource('company_data');

    print('Resource content: $resourceContent');

    // Use resource with AI
    final response = await llmClient.chat(
      "Analyze this company data: $resourceContent",
    );

    print('AI Analysis: ${response.text}');
  } catch (e) {
    print('Resource reading error: $e');
  }
}

Using Resource Templates

Future<void> getResourceWithTemplate() async {
  try {
    final result = await mcpClient.getResourceWithTemplate(
      'files://project/{filename}',
      {'filename': 'config.json'},
    );

    print('Template resource result: $result');
  } catch (e) {
    print('Template resource error: $e');
  }
}

Managing Multiple MCP Clients

For more complex applications, you might need to manage multiple MCP clients:

Registering Multiple MCP Clients

// Create LlmClient with multiple MCP clients
final llmClient = await mcpLlm.createClient(
  providerName: 'claude',
  config: LlmConfiguration(
    apiKey: 'your-claude-api-key',
    model: 'claude-3-haiku-20240307',
  ),
  mcpClients: {
    'tools': toolsClient,
    'resources': resourcesClient,
  },
  systemPrompt: 'You are a helpful assistant with access to various tools and resources.',
);

Managing MCP Clients

// Add a new MCP client to an existing LlmClient
await mcpLlm.addMcpClientToLlmClient(
  'main_client',  // LlmClient ID
  'prompts',      // New MCP client ID
  promptsClient,  // MCP client instance
);

// Remove an MCP client
await mcpLlm.removeMcpClientFromLlmClient(
  'main_client',  // LlmClient ID
  'tools',        // MCP client ID to remove
);

// Set default MCP client
await mcpLlm.setDefaultMcpClient(
  'main_client',  // LlmClient ID
  'resources',    // MCP client ID to set as default
);

// Get list of registered MCP client IDs
final mcpIds = mcpLlm.getMcpClientIds('main_client');

Implementing a Sample App

Let's implement a sample Flutter app that integrates LlmClient with mcp_client to create a tool-augmented AI assistant.

First, let's create an AiService class to handle the integration:

// lib/services/ai_service.dart
import 'dart:async';
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'package:mcp_llm/mcp_llm.dart';
import 'package:mcp_client/mcp_client.dart' as mcp;

class AiService {
  late McpLlm _mcpLlm;
  LlmClient? _llmClient;
  mcp.Client? _mcpClient;
  final _connectionStateController = StreamController<bool>.broadcast();

  Stream<bool> get connectionState => _connectionStateController.stream;
  bool get isConnected => _mcpClient != null && _mcpClient!.isConnected;

  // Initialize service
  Future<void> initialize() async {
    try {
      // Create McpLlm instance
      _mcpLlm = McpLlm();
      _mcpLlm.registerProvider('claude', ClaudeProviderFactory());

      // Set up MCP client
      await _setupMcpClient();

      // Set up LLM client
      await _setupLlmClient();

      // Successfully initialized
      _connectionStateController.add(true);
    } catch (e) {
      print('AI service initialization error: $e');
      _connectionStateController.add(false);
      rethrow;
    }
  }

  Future<void> _setupMcpClient() async {
    final serverUrl = dotenv.env['MCP_SERVER_URL'] ?? '';
    final authToken = dotenv.env['MCP_AUTH_TOKEN'] ?? '';

    if (serverUrl.isEmpty || authToken.isEmpty) {
      throw Exception('Please set MCP server URL and auth token');
    }

    // Create MCP client
    _mcpClient = mcp.McpClient.createClient(
      name: 'flutter_app',
      version: '1.0.0',
      capabilities: mcp.ClientCapabilities(
        roots: true,
        rootsListChanged: true,
        sampling: true,
      ),
    );

    // Create transport
    final transport = await mcp.McpClient.createSseTransport(
      serverUrl: serverUrl,
      headers: {'Authorization': 'Bearer $authToken'},
    );

    // Set up event handling for connection state changes
    bool isConnectedState = false;

    // Handle connection state changes
    _mcpClient!.onNotification('connection_state_changed', (params) {
      final state = params['state'] as String;
      isConnectedState = state == 'connected';
      print('MCP connection state: $state');
      _connectionStateController.add(isConnectedState);
    });

    // Connect to server
    await _mcpClient!.connectWithRetry(
      transport,
      maxRetries: 3,
      delay: const Duration(seconds: 2),
    );

    // Update initial connection state
    _connectionStateController.add(true);
  }

  Future<void> _setupLlmClient() async {
    final apiKey = dotenv.env['CLAUDE_API_KEY'] ?? '';

    if (apiKey.isEmpty) {
      throw Exception('Please set Claude API key');
    }

    // Create LLM client
    _llmClient = await _mcpLlm.createClient(
      providerName: 'claude',
      config: LlmConfiguration(
        apiKey: apiKey,
        model: 'claude-3-haiku-20240307',
        options: {
          'temperature': 0.7,
          'max_tokens': 1500,
        },
      ),
      mcpClient: _mcpClient,
      systemPrompt: 'You are a helpful assistant with access to various tools and resources. Provide concise and accurate responses.',
    );
  }

  // Get available tools
  Future<List<mcp.Tool>> getAvailableTools() async {
    if (_mcpClient == null || !isConnected) {
      throw Exception('MCP client is not connected');
    }

    return await _mcpClient!.listTools();
  }

  // Chat with AI (with tools enabled)
  Future<LlmResponse> chat(String message, {bool enableTools = true}) async {
    if (_llmClient == null) {
      throw Exception('LLM client not initialized');
    }

    return await _llmClient!.chat(
      message,
      enableTools: enableTools,
    );
  }

  // Stream chat responses
  Stream<dynamic> streamChat(String message, {bool enableTools = true}) {
    if (_llmClient == null) {
      throw Exception('LLM client not initialized');
    }

    return _llmClient!.streamChat(
      message,
      enableTools: enableTools,
    );
  }

  // Execute tool directly
  Future<dynamic> executeTool(String toolName, Map<String, dynamic> arguments) async {
    if (_llmClient == null) {
      throw Exception('LLM client not initialized');
    }

    return await _llmClient!.executeTool(
      toolName,
      arguments,
    );
  }

  // Get resource
  Future<dynamic> getResource(String resourceName, {Map<String, dynamic>? params}) async {
    if (_mcpClient == null || !isConnected) {
      throw Exception('MCP client is not connected');
    }

    return await _mcpClient!.readResource(resourceName);
  }

  // Get resource with template
  Future<dynamic> getResourceWithTemplate(String templateUri, Map<String, dynamic> params) async {
    if (_mcpClient == null || !isConnected) {
      throw Exception('MCP client is not connected');
    }

    return await _mcpClient!.getResourceWithTemplate(templateUri, params);
  }

  // Cleanup
  Future<void> dispose() async {
    await _mcpLlm.shutdown();
    _connectionStateController.close();
  }
}

Next, let's create a simple chat UI that uses this service:

// lib/main.dart
import 'dart:async';
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'services/ai_service.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await dotenv.load();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'AI Tool Assistant',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const AiAssistantScreen(),
    );
  }
}

class AiAssistantScreen extends StatefulWidget {
  const AiAssistantScreen({super.key});

  @override
  _AiAssistantScreenState createState() => _AiAssistantScreenState();
}

class _AiAssistantScreenState extends State<AiAssistantScreen> {
  final TextEditingController _textController = TextEditingController();
  final List<ChatMessage> _messages = [];
  final AiService _aiService = AiService();
  bool _isConnected = false;
  bool _isTyping = false;

  @override
  void initState() {
    super.initState();
    _initializeAiService();
  }

  Future<void> _initializeAiService() async {
    try {
      await _aiService.initialize();

      _aiService.connectionState.listen((connected) {
        setState(() {
          _isConnected = connected;
        });
      });

      // List available tools
      final tools = await _aiService.getAvailableTools();
      setState(() {
        _messages.add(ChatMessage(
          text: 'Available tools:\n' +
              tools.map((t) => '- ${t.name}: ${t.description}').join('\n'),
          isUser: false,
        ));
      });
    } catch (e) {
      _showError('AI service initialization error: $e');
    }
  }

  void _showError(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    );
  }

  void _handleSubmitted(String text) async {
    if (text.trim().isEmpty) return;

    _textController.clear();

    setState(() {
      _messages.add(ChatMessage(
        text: text,
        isUser: true,
      ));
      _isTyping = true;
    });

    try {
      if (text.startsWith('/stream')) {
        // Streaming mode
        await _handleStreamChat(text.replaceFirst('/stream', '').trim());
      } else if (text.startsWith('/tool ')) {
        // Direct tool call
        await _handleDirectToolCall(text.replaceFirst('/tool ', '').trim());
      } else {
        // Regular chat
        final response = await _aiService.chat(text);

        // Extract tool call information
        final List<Map<String, dynamic>> toolCallsList = [];
        if (response.toolCalls != null) {
          for (var i = 0; i < response.toolCalls!.length; i++) {
            final call = response.toolCalls![i];
            toolCallsList.add({
              'name': call.name,
              'arguments': call.arguments,
            });
          }
        }

        setState(() {
          _messages.add(ChatMessage(
            text: response.text,
            isUser: false,
            toolCalls: toolCallsList,
          ));
          _isTyping = false;
        });
      }
    } catch (e) {
      _showError('Error: $e');
      setState(() {
        _isTyping = false;
      });
    }
  }

  Future<void> _handleStreamChat(String text) async {
    // Add temporary message for streaming response
    final int messageIndex = _messages.length;
    setState(() {
      _messages.add(ChatMessage(
        text: 'Generating...',
        isUser: false,
      ));
    });

    final StringBuffer fullResponse = StringBuffer();
    final List<Map<String, dynamic>> toolCallsList = [];

    try {
      final responseStream = _aiService.streamChat(text);

      await for (final chunk in responseStream) {
        // Add text chunks to response
        if (chunk['textChunk'] != null && chunk['textChunk'].isNotEmpty) {
          fullResponse.write(chunk['textChunk']);

          setState(() {
            _messages[messageIndex] = ChatMessage(
              text: fullResponse.toString(),
              isUser: false,
              toolCalls: toolCallsList,
            );
          });
        }

        // Add tool call info to list
        if (chunk['toolCalls'] != null) {
          final calls = chunk['toolCalls'] as List;
          for (var i = 0; i < calls.length; i++) {
            toolCallsList.add({
              'name': calls[i]['name'],
              'arguments': calls[i]['arguments'],
            });
          }

          setState(() {
            _messages[messageIndex] = ChatMessage(
              text: fullResponse.toString(),
              isUser: false,
              toolCalls: toolCallsList,
            );
          });
        }

        // Check for stream completion
        if (chunk['isDone'] == true) {
          setState(() {
            _isTyping = false;
          });
        }
      }
    } catch (e) {
      _showError('Streaming error: $e');
      setState(() {
        _isTyping = false;
      });
    }
  }

  Future<void> _handleDirectToolCall(String text) async {
    // Tool command format: /tool {toolName} {arguments(JSON)}
    final parts = text.split(' ');
    if (parts.length < 2) {
      _showError('Invalid tool call format. Use "/tool toolName {arguments}" format.');
      setState(() {
        _isTyping = false;
      });
      return;
    }

    final toolName = parts[0];
    final argsText = parts.sublist(1).join(' ');
    Map<String, dynamic> args;

    try {
      args = jsonDecode(argsText);
    } catch (e) {
      _showError('Arguments are not valid JSON: $e');
      setState(() {
        _isTyping = false;
      });
      return;
    }

    try {
      final result = await _aiService.executeTool(toolName, args);

      setState(() {
        _messages.add(ChatMessage(
          text: 'Tool execution result: $result',
          isUser: false,
        ));
        _isTyping = false;
      });
    } catch (e) {
      _showError('Tool execution error: $e');
      setState(() {
        _isTyping = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('AI Tool Assistant'),
        actions: [
          Icon(
            _isConnected ? Icons.cloud_done : Icons.cloud_off,
            color: _isConnected ? Colors.green : Colors.red,
          ),
          const SizedBox(width: 16),
        ],
      ),
      body: Column(
        children: [
          Expanded(
            child: ListView.builder(
              padding: const EdgeInsets.all(8.0),
              itemCount: _messages.length,
              itemBuilder: (_, index) => _messages[index],
            ),
          ),
          if (_isTyping)
            const Padding(
              padding: EdgeInsets.all(8.0),
              child: Row(
                mainAxisAlignment: MainAxisAlignment.start,
                children: [
                  CircularProgressIndicator(),
                  SizedBox(width: 8),
                  Text('AI is typing...'),
                ],
              ),
            ),
          const Divider(height: 1.0),
          Container(
            decoration: BoxDecoration(
              color: Theme.of(context).cardColor,
            ),
            child: _buildTextComposer(),
          ),
        ],
      ),
    );
  }

  Widget _buildTextComposer() {
    return IconTheme(
      data: IconThemeData(color: Theme.of(context).colorScheme.primary),
      child: Container(
        margin: const EdgeInsets.symmetric(horizontal: 8.0),
        padding: const EdgeInsets.symmetric(horizontal: 8.0, vertical: 8.0),
        child: Row(
          children: [
            Flexible(
              child: TextField(
                controller: _textController,
                onSubmitted: _handleSubmitted,
                decoration: const InputDecoration.collapsed(
                  hintText: 'Send a message (supports /stream and /tool commands)',
                ),
              ),
            ),
            Container(
              margin: const EdgeInsets.symmetric(horizontal: 4.0),
              child: IconButton(
                icon: const Icon(Icons.send),
                onPressed: () => _handleSubmitted(_textController.text),
              ),
            ),
          ],
        ),
      ),
    );
  }

  @override
  void dispose() {
    _aiService.dispose();
    _textController.dispose();
    super.dispose();
  }
}

class ChatMessage extends StatelessWidget {
  final String text;
  final bool isUser;
  final List<Map<String, dynamic>> toolCalls;

  const ChatMessage({
    super.key,
    required this.text,
    required this.isUser,
    this.toolCalls = const [],
  });

  @override
  Widget build(BuildContext context) {
    return Container(
      margin: const EdgeInsets.symmetric(vertical: 10.0),
      child: Row(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Container(
            margin: const EdgeInsets.only(right: 16.0),
            child: CircleAvatar(
              backgroundColor: isUser 
                  ? Theme.of(context).colorScheme.primary 
                  : Theme.of(context).colorScheme.secondary,
              child: Text(isUser ? 'You' : 'AI'),
            ),
          ),
          Expanded(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  isUser ? 'You' : 'AI Assistant',
                  style: Theme.of(context).textTheme.titleMedium,
                ),
                Container(
                  margin: const EdgeInsets.only(top: 5.0),
                  child: Text(text),
                ),
                // Display tool call information
                if (toolCalls.isNotEmpty)
                  Container(
                    margin: const EdgeInsets.only(top: 10.0),
                    padding: const EdgeInsets.all(8.0),
                    decoration: BoxDecoration(
                      color: Colors.grey[200],
                      borderRadius: BorderRadius.circular(8.0),
                    ),
                    child: Column(
                      crossAxisAlignment: CrossAxisAlignment.start,
                      children: [
                        Text(
                          'Tools used:',
                          style: Theme.of(context).textTheme.bodySmall!.copyWith(
                            fontWeight: FontWeight.bold,
                          ),
                        ),
                        ...toolCalls.map((toolCall) => Padding(
                          padding: const EdgeInsets.only(top: 4.0),
                          child: Text(
                            '- ${toolCall["name"] ?? "Unknown"}: ${jsonEncode(toolCall["arguments"] ?? {})}',
                            style: Theme.of(context).textTheme.bodySmall,
                          ),
                        )),
                      ],
                    ),
                  ),
              ],
            ),
          ),
        ],
      ),
    );
  }
}

This sample application demonstrates the key capabilities of the integration:

Connection to an MCP server and displaying available tools
Chatting with AI with tool usage enabled
Streaming responses
Direct tool calls with the /tool command
Display of tool call information
Connection status indicator

Next Steps

After mastering the integration between LlmClient and mcp_client, consider exploring these advanced topics:

LlmServer and mcp_server Integration: Learn how to provide AI capabilities as a service.
Multiple LLM Provider Integration: Leverage different AI models (Claude, GPT, etc.) with MCP ecosystem.
MCP Plugin System: Develop custom tools and resources as plugins.
Distributed MCP Environments: Build complex systems with multiple MCP clients and servers.
Building MCP-based RAG Systems: Implement knowledge-based AI systems with document retrieval.

The integration between LlmClient and mcp_client opens up numerous possibilities for building AI-powered Flutter applications that can interact with external tools and resources. This approach transforms AI from simple text generation to a genuine interactive system that can perform real-world tasks.

Resources

Support the Developer

If you found this article helpful, please consider supporting the development of more free content through Patreon. Your support makes a big difference!

Tags: #Flutter #AI #MCP #LLM #Dart #Claude #OpenAI #ModelContextProtocol #AIIntegration #mcp_client #LlmClient

Integrating AI with Flutter: A Comprehensive Guide to mcp_llm

MCP Dev Studio — Thu, 01 May 2025 07:47:08 +0000

Originally published at GitHub

Introduction

In the rapidly evolving landscape of app development, artificial intelligence (AI) integration has become a critical feature for modern applications. Flutter developers seeking to incorporate AI capabilities into their apps face several challenges: choosing the right AI provider, managing API integrations, handling tokens and rate limits, and creating a smooth user experience.

The mcp_llm package addresses these challenges by providing a unified interface to multiple AI providers, along with powerful tools for building AI-powered Flutter applications. This article—the third in our Model Context Protocol (MCP) series following our explorations of mcp_server and mcp_client—introduces you to the mcp_llm package and demonstrates how to integrate AI capabilities into your Flutter apps.

Understanding mcp_llm
Core Architecture
Getting Started
Basic Usage
Building an AI Chat Application
Advanced Features Preview
Best Practices
Conclusion

Understanding mcp_llm

The mcp_llm package is a powerful toolkit for integrating Large Language Models (LLMs) with Flutter and Dart applications. It builds upon the Model Context Protocol (MCP), providing a standardized way for AI models to interact with external tools, access resources, and communicate with your application.

Key Features

Multiple LLM provider support: Claude (Anthropic), OpenAI, Together AI, and extensible custom providers
Client/Server implementations: LlmClient for app integration, LlmServer for service provision
MCP Integration: Seamless integration with mcp_client and mcp_server
Plugin system: Extensible architecture for tools, prompts, and resources
Parallel processing: Query multiple LLMs simultaneously and aggregate results
RAG capabilities: Document storage and vector search integration
Performance monitoring: Track response times, success rates, and more

Use Cases

The mcp_llm package enables a wide range of AI-powered applications:

Intelligent chatbots and virtual assistants
Document analysis and summarization systems
Code generation and assistance tools
Knowledge-based question-answering systems
Multimodal content creation and analysis
Enterprise data integration and analysis

Core Architecture

The core architecture of mcp_llm consists of several key components:

1. McpLlm

The main class that serves as the entry point for the package. It handles provider registration, client/server creation, plugin management, and more.

// Create an McpLlm instance
final mcpLlm = McpLlm();

// Register providers
mcpLlm.registerProvider('claude', ClaudeProviderFactory());
mcpLlm.registerProvider('openai', OpenAiProviderFactory());

2. LlmClient

The client-side implementation that communicates with AI models and integrates with mcp_client. It sends queries to the AI model, receives responses, and handles tool calls.

// Create an LlmClient
final client = await mcpLlm.createClient(
  providerName: 'claude',
  config: LlmConfiguration(
    apiKey: 'your-api-key',
    model: 'claude-3-haiku-20240307',
  ),
);

// Chat with the AI
final response = await client.chat("What's the weather like today?");

3. LlmServer

The server-side implementation that provides AI capabilities as a service and integrates with mcp_server. It processes requests from external clients and exposes AI functionality.

// Create an LlmServer
final server = await mcpLlm.createServer(
  providerName: 'openai',
  config: LlmConfiguration(
    apiKey: 'your-api-key',
    model: 'gpt-4',
  ),
);

// Register a local tool
server.registerLocalTool(
  name: 'calculator',
  description: 'Performs calculations',
  inputSchema: {...},
  handler: calculatorHandler,
);

4. LLM Providers

Implementation classes that communicate with specific LLM APIs. Each provider implements the LlmInterface and handles communication with a specific LLM service.

// Supported providers
mcpLlm.registerProvider('claude', ClaudeProviderFactory());
mcpLlm.registerProvider('openai', OpenAiProviderFactory());
mcpLlm.registerProvider('together', TogetherProviderFactory());

5. Plugin System

An extensible plugin system that allows registering and managing additional functionality through plugins.

// Register a plugin
await mcpLlm.registerPlugin(myToolPlugin);

6. RAG Components

Components that handle document storage, embedding management, vector search, and other RAG (Retrieval Augmented Generation) capabilities.

// Create a retrieval manager
final retrievalManager = mcpLlm.createRetrievalManager(
  providerName: 'openai',
  documentStore: documentStore,
);

Getting Started

Installation

Add the mcp_llm dependency to your pubspec.yaml file:

dependencies:
  mcp_llm: ^0.2.2
  flutter:
    sdk: flutter

Or install it from the command line:

flutter pub add mcp_llm

API Key Setup

You'll need API keys for the LLM providers you intend to use. Here's how to set up keys for the main providers:

// API key setup examples
final claudeConfig = LlmConfiguration(
  apiKey: 'your-claude-api-key',
  model: 'claude-3-haiku-20240307',
);

final openAiConfig = LlmConfiguration(
  apiKey: 'your-openai-api-key',
  model: 'gpt-4',
);

final togetherConfig = LlmConfiguration(
  apiKey: 'your-together-api-key',
  model: 'mixtral-8x7b-instruct',
);

For security, it's recommended to store API keys in environment variables or secure storage:

// Load API key from environment variable
final apiKey = Platform.environment['CLAUDE_API_KEY'] ?? 
  await secureStorage.read(key: 'claude_api_key');

Basic Usage

Creating McpLlm Instance and Registering Providers

import 'package:mcp_llm/mcp_llm.dart';

void main() async {
  // Create McpLlm instance
  final mcpLlm = McpLlm();

  // Optional logging setup
  final logger = Logger.getLogger('mcp_llm.main');
  logger.setLevel(LogLevel.debug);

  // Register providers
  mcpLlm.registerProvider('claude', ClaudeProviderFactory());
  mcpLlm.registerProvider('openai', OpenAiProviderFactory());

  // Check available providers and capabilities
  final capabilities = mcpLlm.getProviderCapabilities();
  logger.info('Available providers: ${capabilities.keys.join(', ')}');

  // Clean up resources
  await mcpLlm.shutdown();
}

Creating and Using LlmClient

// Create LlmClient
final client = await mcpLlm.createClient(
  providerName: 'claude',
  config: LlmConfiguration(
    apiKey: 'your-claude-api-key',
    model: 'claude-3-haiku-20240307',
    options: {
      'temperature': 0.7,
      'max_tokens': 1500,
    },
  ),
  systemPrompt: 'You are a helpful assistant specialized in Flutter development.',
);

// Chat with AI
final response = await client.chat(
  "What's the best state management approach for Flutter?",
);

print('AI Response: ${response.text}');

Handling Streaming Responses

For real-time responses, you can use streaming:

// Streaming response
final responseStream = client.streamChat(
  "Explain how Flutter's widget tree works",
);

// Handle response chunks
await for (final chunk in responseStream) {
  // Process response chunk
  print('Chunk: ${chunk.textChunk}');

  // Check if complete
  if (chunk.isDone) {
    print('Response completed');
    break;
  }
}

Creating and Using LlmServer

// Create LlmServer
final server = await mcpLlm.createServer(
  providerName: 'openai',
  config: LlmConfiguration(
    apiKey: 'your-openai-api-key',
    model: 'gpt-4',
  ),
);

// Register local tool
server.registerLocalTool(
  name: 'calculator',
  description: 'Performs basic arithmetic operations',
  inputSchema: {
    'type': 'object',
    'properties': {
      'operation': {
        'type': 'string',
        'enum': ['add', 'subtract', 'multiply', 'divide'],
      },
      'a': {'type': 'number'},
      'b': {'type': 'number'},
    },
    'required': ['operation', 'a', 'b'],
  },
  handler: (args) async {
    final operation = args['operation'] as String;
    final a = args['a'] as num;
    final b = args['b'] as num;

    switch (operation) {
      case 'add': return {'result': a + b};
      case 'subtract': return {'result': a - b};
      case 'multiply': return {'result': a * b};
      case 'divide': return {'result': a / b};
      default: throw ArgumentError('Unknown operation: $operation');
    }
  },
);

// Process query
final result = await server.processQuery(
  query: "What's 25 + 17?",
  useLocalTools: true,
);

print('AI Response: ${result.text}');

Building an AI Chat Application

Now, let's build a simple AI chat application using Flutter and the mcp_llm package.

1. Project Setup

Create a new Flutter project and add the required dependencies:

flutter create ai_chat_app
cd ai_chat_app
flutter pub add mcp_llm

2. Secure API Key Management

For security, we'll manage API keys using environment variables or secure storage. For this example, we'll use a direct approach for simplicity, but in a production app, you should use a more secure method.

3. Implementing the Chat App

Create a new file lib/main.dart with the following code:

import 'package:flutter/material.dart';
import 'package:mcp_llm/mcp_llm.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'AI Chat App',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const ChatScreen(),
    );
  }
}

class ChatScreen extends StatefulWidget {
  const ChatScreen({super.key});

  @override
  _ChatScreenState createState() => _ChatScreenState();
}

class _ChatScreenState extends State<ChatScreen> {
  final TextEditingController _textController = TextEditingController();
  final List<ChatMessage> _messages = [];
  late McpLlm _mcpLlm;
  LlmClient? _client;
  bool _isTyping = false;

  @override
  void initState() {
    super.initState();
    _initializeLlm();
  }

  Future<void> _initializeLlm() async {
    _mcpLlm = McpLlm();
    _mcpLlm.registerProvider('claude', ClaudeProviderFactory());

    // API key - replace with your actual key or use secure storage
    const apiKey = 'your-claude-api-key'; 

    if (apiKey.isEmpty) {
      _showError('API key not found');
      return;
    }

    try {
      _client = await _mcpLlm.createClient(
        providerName: 'claude',
        config: LlmConfiguration(
          apiKey: apiKey,
          model: 'claude-3-haiku-20240307',
          options: {
            'temperature': 0.7,
            'max_tokens': 1500,
          },
        ),
        systemPrompt: 'You are a helpful assistant. Be concise and friendly.',
      );
    } catch (e) {
      _showError('Failed to initialize AI: $e');
    }
  }

  void _showError(String message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    );
  }

  void _handleSubmitted(String text) async {
    if (text.trim().isEmpty) return;

    _textController.clear();

    setState(() {
      _messages.add(ChatMessage(
        text: text,
        isUser: true,
      ));
      _isTyping = true;
    });

    if (_client == null) {
      _showError('AI client not initialized');
      setState(() {
        _isTyping = false;
      });
      return;
    }

    try {
      final response = await _client!.chat(text);

      setState(() {
        _messages.add(ChatMessage(
          text: response.text,
          isUser: false,
        ));
        _isTyping = false;
      });
    } catch (e) {
      _showError('Error getting AI response: $e');
      setState(() {
        _isTyping = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('AI Chat App'),
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
      ),
      body: Column(
        children: [
          Flexible(
            child: ListView.builder(
              padding: const EdgeInsets.all(8.0),
              reverse: true,
              itemCount: _messages.length,
              itemBuilder: (_, index) => _messages[_messages.length - 1 - index],
            ),
          ),
          if (_isTyping)
            const Padding(
              padding: EdgeInsets.all(8.0),
              child: Row(
                mainAxisAlignment: MainAxisAlignment.start,
                children: [
                  CircularProgressIndicator(),
                  SizedBox(width: 8),
                  Text('AI is typing...'),
                ],
              ),
            ),
          const Divider(height: 1.0),
          Container(
            decoration: BoxDecoration(
              color: Theme.of(context).cardColor,
            ),
            child: _buildTextComposer(),
          ),
        ],
      ),
    );
  }

  Widget _buildTextComposer() {
    return IconTheme(
      data: IconThemeData(color: Theme.of(context).colorScheme.primary),
      child: Container(
        margin: const EdgeInsets.symmetric(horizontal: 8.0),
        padding: const EdgeInsets.symmetric(horizontal: 8.0, vertical: 8.0),
        child: Row(
          children: [
            Flexible(
              child: TextField(
                controller: _textController,
                onSubmitted: _handleSubmitted,
                decoration: const InputDecoration.collapsed(
                  hintText: 'Send a message',
                ),
              ),
            ),
            Container(
              margin: const EdgeInsets.symmetric(horizontal: 4.0),
              child: IconButton(
                icon: const Icon(Icons.send),
                onPressed: () => _handleSubmitted(_textController.text),
              ),
            ),
          ],
        ),
      ),
    );
  }

  @override
  void dispose() {
    _mcpLlm.shutdown();
    _textController.dispose();
    super.dispose();
  }
}

class ChatMessage extends StatelessWidget {
  final String text;
  final bool isUser;

  const ChatMessage({
    super.key,
    required this.text,
    required this.isUser,
  });

  @override
  Widget build(BuildContext context) {
    return Container(
      margin: const EdgeInsets.symmetric(vertical: 10.0),
      child: Row(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Container(
            margin: const EdgeInsets.only(right: 16.0),
            child: CircleAvatar(
              backgroundColor: isUser 
                  ? Theme.of(context).colorScheme.primary 
                  : Theme.of(context).colorScheme.secondary,
              child: Text(isUser ? 'You' : 'AI'),
            ),
          ),
          Expanded(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  isUser ? 'You' : 'AI Assistant',
                  style: Theme.of(context).textTheme.titleMedium,
                ),
                Container(
                  margin: const EdgeInsets.only(top: 5.0),
                  child: Text(text),
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }
}

4. Network Permissions for macOS

If you're running on macOS, you need to set up network permissions:

App Transport Security Settings

Add the following to macos/Runner/Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

Network Entitlements

Add the following to both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:

<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.network.server</key>
<true/>

5. Run the App

Now you can run the app:

flutter run

The app provides a simple chat interface where users can send messages to the AI and receive responses. It includes features like:

Message list with user and AI messages
Loading indicator while the AI is responding
Error handling and notifications
Clean UI with Material Design 3

Advanced Features Preview

The mcp_llm package offers numerous advanced features that we'll explore in future articles:

1. Streaming Responses

Display AI responses in real-time for a better user experience:

final responseStream = client.streamChat("Explain Flutter widgets");

await for (final chunk in responseStream) {
  // Update UI
  setState(() {
    currentResponse += chunk.textChunk;
  });
}

2. mcp_client Integration

Access external tools and resources:

import 'package:mcp_client/mcp_client.dart';

// Create MCP client
final mcpClient = McpClient.createClient(...);

// Connect to LlmClient
final llmClient = await mcpLlm.createClient(
  providerName: 'claude',
  mcpClient: mcpClient,
  ...
);

3. mcp_server Integration

Provide AI capabilities as a service:

import 'package:mcp_server/mcp_server.dart';

// Create MCP server
final mcpServer = McpServer.createServer(...);

// Connect to LlmServer
final llmServer = await mcpLlm.createServer(
  providerName: 'openai',
  mcpServer: mcpServer,
  ...
);

4. Multiple LLM Providers

Leverage different AI models based on the task:

// Register multiple providers
mcpLlm.registerProvider('claude', ClaudeProviderFactory());
mcpLlm.registerProvider('openai', OpenAiProviderFactory());
mcpLlm.registerProvider('together', TogetherProviderFactory());

// Select client based on query
final client = mcpLlm.selectClient(query);

5. Parallel Processing

Query multiple LLMs simultaneously and aggregate results:

final response = await mcpLlm.executeParallel(
  "What are the pros and cons of Flutter?",
  providerNames: ['claude', 'openai', 'together'],
);

6. RAG (Retrieval Augmented Generation)

Integrate document search results with AI responses:

// Create retrieval manager
final retrievalManager = mcpLlm.createRetrievalManager(...);

// Add documents
await retrievalManager.addDocument(Document(...));

// Search and generate
final answer = await retrievalManager.retrieveAndGenerate(
  "Tell me about Flutter state management",
);

Best Practices

When working with mcp_llm, consider these best practices:

1. API Key Security

Always store API keys securely:

Use environment variables
Use secure storage solutions
Never hardcode keys in source code
Don't include keys in version control

2. Error Handling

Implement robust error handling:

Wrap AI calls in try-catch blocks
Handle network issues gracefully
Provide meaningful error messages to users
Implement retry mechanisms for transient errors

3. Performance Optimization

Optimize performance:

Use streaming responses for better UX
Implement caching where appropriate
Monitor token usage and API costs
Use the performance monitoring features

4. User Experience

Create a smooth user experience:

Show typing indicators during AI processing
Implement timeout handling
Provide fallbacks for unavailable services
Design intuitive interfaces for AI interactions

5. Testing

Thoroughly test your AI integrations:

Unit test your AI-related code
Use mock providers for testing
Test with different query types
Verify error handling scenarios

Conclusion

The mcp_llm package offers a powerful, flexible way to integrate AI capabilities into Flutter applications. By providing a unified interface to multiple LLM providers and robust tools for building AI-powered features, it simplifies the process of creating intelligent apps.

In this article, we've explored the basic concepts and usage of mcp_llm, but we've only scratched the surface of its capabilities. Future articles in this series will delve deeper into advanced features such as LlmClient's tool integration, LlmServer implementation, plugin development, and RAG systems.

With mcp_llm, Flutter developers can leverage the power of large language models while maintaining a clean, modular architecture and a great user experience. Whether you're building a simple chatbot or a complex AI-powered application, mcp_llm provides the tools you need to succeed.

Resources

Support the Developer

If you found this article helpful, please consider supporting the development of more free content through Patreon. Your support makes a big difference!

Tags: #Flutter #AI #MCP #LLM #Dart #Claude #OpenAI #ModelContextProtocol #AIIntegration

Building a Model Context Protocol Client with Dart: A Comprehensive Guide

MCP Dev Studio — Thu, 01 May 2025 07:45:28 +0000

Learn how to implement a Model Context Protocol (MCP) client with Dart and communicate with various MCP servers through a step-by-step approach.

Introduction

As AI technologies advance, the need for standardized communication between large language models (LLMs) and local systems becomes increasingly important. The Model Context Protocol (MCP) addresses this need by providing a standardized way for AI models to interact with external environments.

In this article, we'll explore how to implement an MCP client using Dart. This is the second part of our MCP series, following our previous article on Building a Model Context Protocol Server with Dart. The series will continue with future articles on integrating MCP with LLMs.

What is an MCP Client?

An MCP client is a component that communicates with MCP servers using the Model Context Protocol. It serves as a bridge between applications and MCP servers, enabling the use of tools, resources, and prompts provided by the server.

Key functionalities of an MCP client include:

Server connection management: Establishing and maintaining connections to MCP servers
Server capability discovery: Querying available tools, resources, and prompts
Tool invocation: Remotely calling functions registered on the server
Resource access: Accessing data sources provided by the server
Event handling: Processing events and notifications from the server

The MCP client provides a clean, programmatic interface to these capabilities, making it easy to integrate them into applications.

Project Setup

Let's start by setting up a new Dart project and installing the necessary dependencies.

# Create a new Dart project
dart create mcp_client_example
cd mcp_client_example

Next, update the pubspec.yaml file to include the MCP client package:

name: mcp_client_example
description: Example of MCP client implementation
version: 1.0.0

environment:
  sdk: ^3.7.2

dependencies:
  mcp_client: ^0.1.7
  uuid: ^4.0.0
  http: ^1.1.0

dev_dependencies:
  lints: ^5.0.0
  test: ^1.24.0

Install the dependencies:

dart pub get

Initializing the Client

Now let's create a basic MCP client. Create a file named mcp_client_example.dart in the bin directory:

import 'dart:io';
import 'package:mcp_client/mcp_client.dart';

final Logger _logger = Logger.getLogger('mcp_client_example');

/// MCP client example application
void main() async {
  // Set up logging
  _logger.setLevel(LogLevel.debug);

  // Create a log file
  final logFile = File('mcp_client_example.log');
  final logSink = logFile.openWrite();

  logToConsoleAndFile('Starting MCP client example...', _logger, logSink);

  try {
    // Create a client with specific capabilities
    final client = McpClient.createClient(
      name: 'Example MCP Client',
      version: '1.0.0',
      capabilities: ClientCapabilities(
        roots: true,
        rootsListChanged: true,
        sampling: true,
      ),
    );

    logToConsoleAndFile('Client initialized successfully.', _logger, logSink);

    // Connect to a server (implemented in the next section)

  } catch (e) {
    logToConsoleAndFile('Error: $e', _logger, logSink);
  } finally {
    // Close the log file
    await logSink.flush();
    await logSink.close();
  }
}

/// Log to both console and file
void logToConsoleAndFile(String message, Logger logger, IOSink logSink) {
  // Log to console
  logger.debug(message);

  // Log to file
  logSink.writeln(message);
}

The ClientCapabilities object specifies which features the client supports:

roots: Support for root management
rootsListChanged: Support for notifications when the root list changes
sampling: Support for sampling (needed for LLM integration)

Connecting to Servers

MCP clients can connect to servers using two primary transport mechanisms:

STDIO Transport

STDIO (Standard Input/Output) transport communicates through standard input/output streams. This is useful for connecting to local MCP servers that run as separate processes.

// Create an STDIO transport to connect to a filesystem MCP server
final transport = await McpClient.createStdioTransport(
  command: 'npx',
  arguments: ['-y', '@modelcontextprotocol/server-filesystem', Directory.current.path],
);

logToConsoleAndFile('STDIO transport mechanism created.', _logger, logSink);

// Connect to the server
await client.connect(transport);
logToConsoleAndFile('Successfully connected to server!', _logger, logSink);

This example connects to a Node.js-based filesystem MCP server. The command and arguments parameters specify how to launch the external process.

SSE Transport

SSE (Server-Sent Events) transport communicates over HTTP. This is suitable for connecting to web-based MCP servers.

// Create an SSE transport
final transport = await McpClient.createSseTransport(
  serverUrl: 'http://localhost:8080',
  headers: {'Authorization': 'Bearer your-token'},
);

// Connect with retry options
await client.connectWithRetry(
  transport,
  maxRetries: 3,
  delay: const Duration(seconds: 2),
);

The SSE transport requires a server URL and optionally headers. The connectWithRetry method attempts to reconnect automatically if the initial connection fails.

Registering Notification Handlers

After connecting to a server, we can register handlers for various notifications:

// Register notification handlers
client.onToolsListChanged(() {
  logToConsoleAndFile('Tools list has changed!', _logger, logSink);
});

client.onResourcesListChanged(() {
  logToConsoleAndFile('Resources list has changed!', _logger, logSink);
});

client.onResourceUpdated((uri) {
  logToConsoleAndFile('Resource has been updated: $uri', _logger, logSink);
});

client.onLogging((level, message, logger, data) {
  logToConsoleAndFile('Server log [$level]: $message', _logger, logSink);
});

These handlers will be called when the corresponding events occur on the server.

Working with Tools and Resources

Now let's explore how to use tools and resources provided by the server.

Listing and Calling Tools

try {
  // Get available tools
  final tools = await client.listTools();
  logToConsoleAndFile('\n--- Available Tools ---', _logger, logSink);

  if (tools.isEmpty) {
    logToConsoleAndFile('No tools available.', _logger, logSink);
  } else {
    for (final tool in tools) {
      logToConsoleAndFile('Tool: ${tool.name} - ${tool.description}', _logger, logSink);
    }
  }

  // Call a specific tool: list directory contents
  if (tools.any((tool) => tool.name == 'list_directory')) {
    logToConsoleAndFile('\n--- Listing Current Directory ---', _logger, logSink);

    final result = await client.callTool('list_directory', {
      'path': Directory.current.path
    });

    if (result.isError == true) {
      logToConsoleAndFile('Error: ${(result.content.first as TextContent).text}', _logger, logSink);
    } else {
      final contentText = (result.content.first as TextContent).text;
      logToConsoleAndFile('Directory contents:', _logger, logSink);
      logToConsoleAndFile(contentText, _logger, logSink);
    }
  }
} catch (e) {
  logToConsoleAndFile('Error working with tools: $e', _logger, logSink);
}

Listing and Reading Resources

try {
  // Get available resources
  final resources = await client.listResources();
  logToConsoleAndFile('\n--- Available Resources ---', _logger, logSink);

  if (resources.isEmpty) {
    logToConsoleAndFile('No resources available.', _logger, logSink);
  } else {
    for (final resource in resources) {
      logToConsoleAndFile('Resource: ${resource.name} (${resource.uri})', _logger, logSink);
    }

    // Read a file resource
    if (resources.any((resource) => resource.uri.startsWith('file:'))) {
      final readmeFile = 'README.md';
      if (await File(readmeFile).exists()) {
        logToConsoleAndFile('\n--- Reading README.md via resource ---', _logger, logSink);

        try {
          final fullPath = '${Directory.current.path}/$readmeFile';
          final resourceResult = await client.readResource('file://$fullPath');

          if (resourceResult.contents.isEmpty) {
            logToConsoleAndFile('Resource has no content.', _logger, logSink);
          } else {
            final content = resourceResult.contents.first.text ?? '';

            // Show partial content if too long
            if (content.length > 500) {
              logToConsoleAndFile('${content.substring(0, 500)}...\n(Content truncated)', _logger, logSink);
            } else {
              logToConsoleAndFile(content, _logger, logSink);
            }
          }
        } catch (e) {
          logToConsoleAndFile('Error reading resource: $e', _logger, logSink);
        }
      }
    }
  }
} catch (e) {
  logToConsoleAndFile('Resources functionality not supported: $e', _logger, logSink);
}

Practical Example: Filesystem Server Integration

Let's create a complete example that communicates with a filesystem MCP server. First, we need to install the server:

npm install -g @modelcontextprotocol/server-filesystem

Now, let's implement a client that interacts with this server:

import 'dart:io';
import 'dart:convert';
import 'package:mcp_client/mcp_client.dart';

/// MCP client example application
void main() async {
  final Logger _logger = Logger.getLogger('mcp_client_example');
  _logger.setLevel(LogLevel.debug);

  // Create a log file
  final logFile = File('mcp_client_example.log');
  final logSink = logFile.openWrite();

  logToConsoleAndFile('Starting MCP client example...', _logger, logSink);

  try {
    // Create a client
    final client = McpClient.createClient(
      name: 'Example MCP Client',
      version: '1.0.0',
      capabilities: ClientCapabilities(
        roots: true,
        rootsListChanged: true,
        sampling: true,
      ),
    );

    logToConsoleAndFile('Client initialized successfully.', _logger, logSink);

    // Connect to the filesystem MCP server via STDIO
    logToConsoleAndFile('Connecting to MCP filesystem server...', _logger, logSink);

    final transport = await McpClient.createStdioTransport(
      command: 'npx',
      arguments: ['-y', '@modelcontextprotocol/server-filesystem', Directory.current.path],
    );

    logToConsoleAndFile('STDIO transport mechanism created.', _logger, logSink);

    // Establish connection
    await client.connect(transport);
    logToConsoleAndFile('Successfully connected to server!', _logger, logSink);

    // Register notification handlers
    client.onToolsListChanged(() {
      logToConsoleAndFile('Tools list has changed!', _logger, logSink);
    });

    client.onResourcesListChanged(() {
      logToConsoleAndFile('Resources list has changed!', _logger, logSink);
    });

    client.onResourceUpdated((uri) {
      logToConsoleAndFile('Resource has been updated: $uri', _logger, logSink);
    });

    client.onLogging((level, message, logger, data) {
      logToConsoleAndFile('Server log [$level]: $message', _logger, logSink);
    });

    // Check server health (with error handling)
    try {
      final health = await client.healthCheck();
      logToConsoleAndFile('\n--- Server Health Status ---', _logger, logSink);
      logToConsoleAndFile('Server running: ${health.isRunning}', _logger, logSink);
      logToConsoleAndFile('Connected sessions: ${health.connectedSessions}', _logger, logSink);
      logToConsoleAndFile('Registered tools: ${health.registeredTools}', _logger, logSink);
      logToConsoleAndFile('Registered resources: ${health.registeredResources}', _logger, logSink);
      logToConsoleAndFile('Registered prompts: ${health.registeredPrompts}', _logger, logSink);
      logToConsoleAndFile('Uptime: ${health.uptime.inSeconds} seconds', _logger, logSink);
    } catch (e) {
      logToConsoleAndFile('Health check functionality not supported: $e', _logger, logSink);
    }

    // List available tools
    try {
      final tools = await client.listTools();
      logToConsoleAndFile('\n--- Available Tools ---', _logger, logSink);

      if (tools.isEmpty) {
        logToConsoleAndFile('No tools available.', _logger, logSink);
      } else {
        for (final tool in tools) {
          logToConsoleAndFile('Tool: ${tool.name} - ${tool.description}', _logger, logSink);
        }
      }

      // List directory contents
      if (tools.any((tool) => tool.name == 'list_directory')) {
        logToConsoleAndFile('\n--- Current Directory Contents ---', _logger, logSink);

        final result = await client.callTool('list_directory', {
          'path': Directory.current.path
        });

        if (result.isError == true) {
          logToConsoleAndFile('Error: ${(result.content.first as TextContent).text}', _logger, logSink);
        } else {
          final contentText = (result.content.first as TextContent).text;
          logToConsoleAndFile('Directory contents:', _logger, logSink);
          logToConsoleAndFile(contentText, _logger, logSink);
        }
      }

      // Get file information
      if (tools.any((tool) => tool.name == 'get_file_info')) {
        final readmeFile = 'README.md';
        if (await File(readmeFile).exists()) {
          logToConsoleAndFile('\n--- README.md File Information ---', _logger, logSink);

          final infoResult = await client.callTool('get_file_info', {
            'path': '${Directory.current.path}/$readmeFile'
          });

          if (infoResult.isError == true) {
            logToConsoleAndFile('Error: ${(infoResult.content.first as TextContent).text}', _logger, logSink);
          } else {
            final infoText = (infoResult.content.first as TextContent).text;
            logToConsoleAndFile('File info:', _logger, logSink);
            logToConsoleAndFile(infoText, _logger, logSink);
          }
        }
      }

      // Read file contents
      if (tools.any((tool) => tool.name == 'read_file')) {
        final readmeFile = 'README.md';
        if (await File(readmeFile).exists()) {
          logToConsoleAndFile('\n--- Reading README.md File ---', _logger, logSink);

          final readResult = await client.callTool('read_file', {
            'path': '${Directory.current.path}/$readmeFile'
          });

          if (readResult.isError == true) {
            logToConsoleAndFile('Error: ${(readResult.content.first as TextContent).text}', _logger, logSink);
          } else {
            final content = (readResult.content.first as TextContent).text;

            // Truncate if too long
            if (content.length > 500) {
              logToConsoleAndFile('${content.substring(0, 500)}...\n(Content truncated)', _logger, logSink);
            } else {
              logToConsoleAndFile(content, _logger, logSink);
            }
          }
        }
      }
    } catch (e) {
      logToConsoleAndFile('Error listing tools: $e', _logger, logSink);
    }

    // Check resources (with error handling)
    try {
      logToConsoleAndFile('\n--- Checking Resources ---', _logger, logSink);
      final resources = await client.listResources();

      if (resources.isEmpty) {
        logToConsoleAndFile('No resources available.', _logger, logSink);
      } else {
        for (final resource in resources) {
          logToConsoleAndFile('Resource: ${resource.name} (${resource.uri})', _logger, logSink);
        }

        // Try to read README.md as a resource
        final readmeFile = 'README.md';
        if (await File(readmeFile).exists() && 
            resources.any((resource) => resource.uri.startsWith('file:'))) {
          logToConsoleAndFile('\n--- Reading README.md as Resource ---', _logger, logSink);

          try {
            final fullPath = '${Directory.current.path}/$readmeFile';
            final resourceResult = await client.readResource('file://$fullPath');

            if (resourceResult.contents.isEmpty) {
              logToConsoleAndFile('Resource has no content.', _logger, logSink);
            } else {
              final content = resourceResult.contents.first.text ?? '';

              // Truncate if too long
              if (content.length > 500) {
                logToConsoleAndFile('${content.substring(0, 500)}...\n(Content truncated)', _logger, logSink);
              } else {
                logToConsoleAndFile(content, _logger, logSink);
              }
            }
          } catch (e) {
            logToConsoleAndFile('Error reading resource: $e', _logger, logSink);
          }
        }
      }
    } catch (e) {
      logToConsoleAndFile('Resources functionality not supported: $e', _logger, logSink);
    }

    // Wait briefly then exit
    await Future.delayed(Duration(seconds: 2));
    logToConsoleAndFile('\nExample execution completed.', _logger, logSink);

    // Disconnect client
    client.disconnect();
    logToConsoleAndFile('Client disconnected.', _logger, logSink);

  } catch (e, stackTrace) {
    logToConsoleAndFile('Error: $e', _logger, logSink);
    logToConsoleAndFile('Stack trace: $stackTrace', _logger, logSink);
  } finally {
    // Close log file
    await logSink.flush();
    await logSink.close();
  }
}

/// Log to both console and file
void logToConsoleAndFile(String message, Logger logger, IOSink logSink) {
  // Log to console
  logger.debug(message);

  // Log to file
  logSink.writeln(message);
}

Running the Example

To run the example, execute:

dart run bin/mcp_client_example.dart

The output will be displayed in the console and also saved to mcp_client_example.log.

Error Handling and Troubleshooting

When working with MCP clients, you may encounter various errors. Here are some common issues and how to handle them:

Common Errors

Method not found errors

   McpError (-32601): Method not found

This occurs when the client attempts to call a method that doesn't exist on the server. Always wrap method calls in try-catch blocks and check server capabilities first.

Resources not supported

   McpError: Server does not support resources

Some servers only implement tools without resource capabilities. Handle this by checking capabilities or using try-catch blocks.

Connection errors

   Failed to connect to transport

Ensure the server is running and the connection parameters are correct. For STDIO transport, verify the command and arguments.

Debugging Tips

Enable debug logging to see detailed communication between client and server.
Check server capabilities before using features.
Verify tool and resource names, as they can vary between different servers.
Isolate critical API calls in try-catch blocks.

// Example error handling pattern
try {
  // Potentially problematic code
  final result = await client.callTool('tool_name', { 'param': 'value' });
  // Process result
} catch (e) {
  if (e.toString().contains('Method not found')) {
    // Handle missing tool
    print('The tool "tool_name" is not available on this server');
  } else {
    // Handle other errors
    print('Error calling tool: $e');
  }
}

Conclusion

In this article, we've explored how to implement an MCP client using Dart. We've covered:

Setting up a client and configuring capabilities
Connecting to servers using different transport mechanisms (STDIO and SSE)
Working with tools and resources
Handling notifications and events
Properly handling errors and connection issues

The MCP client allows applications to communicate with MCP servers, unlocking powerful capabilities like file system access, API integrations, and more. This enables AI models to interact with local systems in a standardized way.

In our next article, we'll explore integrating MCP with large language models (LLMs) using the mcp_llm package, showing how models like Claude can leverage local system capabilities through MCP.

Building a Model Context Protocol Server with Dart: Connecting to Claude Desktop

MCP Dev Studio — Thu, 01 May 2025 07:41:31 +0000

A step-by-step guide to implementing an MCP server that enables AI models to interact with your local system

Today's AI assistants are becoming increasingly capable, but their ability to interact with our local environments remains limited. The Model Context Protocol (MCP) bridges this gap by providing a standardized way for AI models like Claude to communicate with external tools, access resources, and interact with local systems.

In this guide, we'll implement an MCP server using Flutter and Dart, then connect it to Claude Desktop to unlock powerful new capabilities.

What is Model Context Protocol (MCP)?

Model Context Protocol is a JSON-RPC based protocol that standardizes communication between AI models and external environments. It defines a structured way for AI models to:

Call tools (functions or APIs)
Access resources (files or data sources)
Use prompts (reusable conversation templates)

By implementing an MCP server, you can give AI models like Claude the ability to interact with your local system, access specific files, or call custom functions that you define.

Project Setup

Let's start by setting up our Dart project with the required dependencies.

# Create a new Dart project
dart create mcp_server_example
cd mcp_server_example

Modify the pubspec.yaml file to include the needed dependencies:

name: mcp_server_example
description: A sample MCP server implementation
version: 1.0.0

environment:
  sdk: '>=2.18.0 <3.0.0'

dependencies:
  uuid: ^3.0.7
  mcp_server: ^1.0.0

Run the following command to get the dependencies:

dart pub get

Implementing the MCP Server

Our MCP server implementation will consist of:

Server instance creation
Transport mechanism configuration (STDIO or SSE)
Registration of tools, resources, and prompts
Server startup and connection handling

Here's the basic structure of our implementation:

import 'dart:async';
import 'dart:io';
import 'dart:convert';
import 'package:mcp_server/mcp_server.dart';

final Logger _logger = Logger.getLogger('mcp_server_example');

void main(List<String> args) async {
  _logger.setLevel(LogLevel.debug);

  // STDIO Mode for direct connection with Claude Desktop
  if (args.contains('--mcp-stdio-mode')) {
    await startMcpServer(mode: 'stdio');
  } else {
    // SSE Mode for web connections
    int port = 8999;
    await startMcpServer(mode: 'sse', port: port);
  }
}

The Server Startup Function

Future<void> startMcpServer({required String mode, int port = 8080}) async {
  try {
    // Create server with capabilities
    final server = McpServer.createServer(
      name: 'Flutter MCP Demo',
      version: '1.0.0',
      capabilities: ServerCapabilities(
        tools: true,
        toolsListChanged: true,
        resources: true,
        resourcesListChanged: true,
        prompts: true,
        promptsListChanged: true,
      ),
    );

    // Register tools, resources, and prompts
    _registerTools(server);
    _registerResources(server);
    _registerPrompts(server);

    // Set up transport based on mode
    ServerTransport transport;
    if (mode == 'stdio') {
      _logger.debug('Starting server in STDIO mode');
      transport = McpServer.createStdioTransport();
    } else {
      _logger.debug('Starting server in SSE mode on port $port');
      transport = McpServer.createSseTransport(
        endpoint: '/sse',
        messagesEndpoint: '/message',
        port: port,
        fallbackPorts: [port + 1, port + 2, port + 3],
      );
    }

    // Handle transport closure
    transport.onClose.then((_) {
      _logger.debug('Transport closed, shutting down.');
      exit(0);
    });

    // Connect server to transport
    server.connect(transport);

    // Send initial log message
    server.sendLog(McpLogLevel.info, 'Flutter MCP Server started successfully');

    if (mode == 'sse') {
      _logger.debug('SSE Server is running on:');
      _logger.debug('- SSE endpoint:     http://localhost:$port/sse');
      _logger.debug('- Message endpoint: http://localhost:$port/message');
      _logger.debug('Press Ctrl+C to stop the server');
    } else {
      _logger.debug('STDIO Server initialized and connected to transport');
    }

  } catch (e, stackTrace) {
    _logger.debug('Error initializing MCP server: $e');
    _logger.debug(stackTrace.toString());
    exit(1);
  }
}

Transport Mechanisms: STDIO vs. SSE

MCP servers support two primary transport mechanisms:

STDIO Transport

STDIO transport uses standard input/output streams for communication. This is ideal for direct integration with desktop applications like Claude Desktop.

transport = McpServer.createStdioTransport();

SSE (Server-Sent Events) Transport

SSE transport uses HTTP for communication, making it suitable for web-based applications. The server listens on a specified port and sends events to connected clients.

transport = McpServer.createSseTransport(
  endpoint: '/sse',
  messagesEndpoint: '/message',
  port: port,
  fallbackPorts: [port + 1, port + 2, port + 3],
);

Registering Tools, Resources, and Prompts

Now let's implement the core functionality of our MCP server by registering tools, resources, and prompts.

Tools Registration

Tools are functions that AI models can call. We'll implement a greeting tool, a calculator, and a date/time tool:

void _registerTools(Server server) {
  // Hello world tool
  server.addTool(
    name: 'hello',
    description: 'Says hello to someone',
    inputSchema: {
      'type': 'object',
      'properties': {
        'name': {
          'type': 'string',
          'description': 'Name to say hello to'
        }
      },
      'required': []
    },
    handler: (args) async {
      final name = args['name'] ?? 'world';
      return CallToolResult([TextContent(text: 'Hello, $name!')]);
    },
  );

  // Calculator tool
  server.addTool(
    name: 'calculator',
    description: 'Perform basic arithmetic operations',
    inputSchema: {
      'type': 'object',
      'properties': {
        'operation': {
          'type': 'string',
          'enum': ['add', 'subtract', 'multiply', 'divide'],
          'description': 'Mathematical operation to perform'
        },
        'a': {
          'type': 'number',
          'description': 'First operand'
        },
        'b': {
          'type': 'number',
          'description': 'Second operand'
        }
      },
      'required': ['operation', 'a', 'b']
    },
    handler: (args) async {
      final operation = args['operation'] as String;
      final a = (args['a'] is int) ? (args['a'] as int).toDouble() : args['a'] as double;
      final b = (args['b'] is int) ? (args['b'] as int).toDouble() : args['b'] as double;

      double result;
      switch (operation) {
        case 'add':
          result = a + b;
          break;
        case 'subtract':
          result = a - b;
          break;
        case 'multiply':
          result = a * b;
          break;
        case 'divide':
          if (b == 0) {
            throw McpError('Cannot divide by zero');
          }
          result = a / b;
          break;
        default:
          throw McpError('Unknown operation: $operation');
      }

      return CallToolResult([TextContent(text: 'Result: $result')]);
    },
  );

  // Date and time tool
  server.addTool(
    name: 'currentDateTime',
    description: 'Get the current date and time',
    inputSchema: {
      'type': 'object',
      'properties': {
        'format': {
          'type': 'string',
          'description': 'Output format (full, date, time)',
          'default': 'full'
        }
      },
      'required': []
    },
    handler: (args) async {
      try {
        String format = args['format'] ?? 'full';

        final now = DateTime.now();

        String result;
        switch (format) {
          case 'date':
            result = '${now.year}-${now.month.toString().padLeft(2, '0')}-${now.day.toString().padLeft(2, '0')}';
            break;
          case 'time':
            result = '${now.hour.toString().padLeft(2, '0')}:${now.minute.toString().padLeft(2, '0')}:${now.second.toString().padLeft(2, '0')}';
            break;
          case 'full':
          default:
            result = now.toIso8601String();
            break;
        }

        return CallToolResult([TextContent(text: result)]);
      } catch (e) {
        return CallToolResult(
            [TextContent(text: "Error getting date/time: $e")],
            isError: true
        );
      }
    },
  );
}

Resources Registration

Resources provide access to data sources that AI models can read. We'll implement system information and environment variables resources:

void _registerResources(Server server) {
  // System info resource
  server.addResource(
    uri: 'flutter://system-info',
    name: 'System Information',
    description: 'Detailed information about the current system',
    mimeType: 'application/json',
    uriTemplate: {
      'type': 'object',
      'properties': {}
    },
    handler: (uri, params) async {
      final systemInfo = {
        'operatingSystem': Platform.operatingSystem,
        'operatingSystemVersion': Platform.operatingSystemVersion,
        'localHostname': Platform.localHostname,
        'numberOfProcessors': Platform.numberOfProcessors,
        'localeName': Platform.localeName,
        'executable': Platform.executable,
        'resolvedExecutable': Platform.resolvedExecutable,
        'script': Platform.script.toString(),
      };

      final contents = systemInfo.entries.map((entry) =>
          ResourceContent(
            uri: 'flutter://system-info/${entry.key}',
            text: '${entry.key}: ${entry.value}',
          )
      ).toList();

      return ReadResourceResult(
        content: jsonEncode(systemInfo),
        mimeType: 'application/json',
        contents: contents,
      );
    }
  );

  // Environment variables resource
  server.addResource(
    uri: 'flutter://env-vars',
    name: 'Environment Variables',
    description: 'List of system environment variables',
    mimeType: 'application/json',
    uriTemplate: {
      'type': 'object',
      'properties': {}
    },
    handler: (uri, params) async {
      final envVars = Platform.environment;
      final contents = envVars.entries.map((entry) =>
          ResourceContent(
            uri: 'flutter://env-vars/${entry.key}',
            text: '${entry.key}: ${entry.value}',
          )
      ).toList();

      return ReadResourceResult(
        content: jsonEncode(envVars),
        mimeType: 'application/json',
        contents: contents,
      );
    }
  );
}

Prompts Registration

Prompts are templates for conversations with AI models. We'll implement a greeting prompt and a code review prompt:

void _registerPrompts(Server server) {
  // Simple greeting prompt
  server.addPrompt(
    name: 'greeting',
    description: 'Generate a greeting for a user',
    arguments: [
      PromptArgument(
        name: 'name',
        description: 'Name of the person to greet',
        required: true,
      ),
      PromptArgument(
        name: 'formal',
        description: 'Whether to use formal greeting style',
        required: false,
      ),
    ],
    handler: (args) async {
      final name = args['name'] as String;
      final formal = args['formal'] as bool? ?? false;

      final String systemPrompt = formal
          ? 'You are a formal assistant. Address the user with respect and formality.'
          : 'You are a friendly assistant. Be warm and casual in your tone.';

      final messages = [
        Message(
          role: MessageRole.system.toString().split('.').last,
          content: TextContent(text: systemPrompt),
        ),
        Message(
          role: MessageRole.user.toString().split('.').last,
          content: TextContent(text: 'Please greet $name'),
        ),
      ];

      return GetPromptResult(
        description: 'A ${formal ? 'formal' : 'casual'} greeting for $name',
        messages: messages,
      );
    },
  );

  // Code review prompt
  server.addPrompt(
    name: 'codeReview',
    description: 'Generate a code review for a code snippet',
    arguments: [
      PromptArgument(
        name: 'code',
        description: 'Code to review',
        required: true,
      ),
      PromptArgument(
        name: 'language',
        description: 'Programming language of the code',
        required: true,
      ),
    ],
    handler: (args) async {
      final code = args['code'] as String;
      final language = args['language'] as String;

      final systemPrompt = '''
You are an expert code reviewer. Review the provided code with these guidelines:
1. Identify potential bugs or issues
2. Suggest optimizations for performance or readability
3. Highlight good practices used in the code
4. Provide constructive feedback for improvements
Be specific in your feedback and provide code examples when suggesting changes.
''';

      final messages = [
        Message(
          role: MessageRole.system.toString().split('.').last,
          content: TextContent(text: systemPrompt),
        ),
        Message(
          role: MessageRole.user.toString().split('.').last,
          content: TextContent(text: 'Please review this $language code:\n\n```

$language\n$code\n

```'),
        ),
      ];

      return GetPromptResult(
        description: 'Code review for $language code',
        messages: messages,
      );
    },
  );
}

Connecting to Claude Desktop

Now let's connect our MCP server to Claude Desktop:

Building an Executable File

First, let's compile our Dart code into an executable file:

# Navigate to the project directory
cd /path/to/mcp_server/example

# Compile the Dart file to an executable
dart compile exe bin/mcp_server_example.dart -o mcp_server_example

# Add execute permission
chmod +x mcp_server_example

Configuring Claude Desktop

To connect Claude Desktop with our MCP server:

Launch Claude Desktop
Navigate to Settings > Developer
Click "Edit Config"
This will open the claude_desktop_config.json file. Modify it as follows:

{
    "mcpServers": {
        "flutter-test": {
            "command": "/path/to/mcp_server/example/mcp_server_example",
            "args": ["--mcp-stdio-mode"]
        }
    }
}

Save the file and restart Claude Desktop

Connecting and Using the Server

After restarting Claude Desktop, click on the "MCP" dropdown menu in the bottom left
Select "flutter-test" to connect to your MCP server
When successfully connected, a hammer icon will appear at the bottom of the chat window

Now Claude Desktop has access to the tools, resources, and prompts we've registered:

The hello tool to generate greetings
The calculator tool to perform arithmetic operations
The currentDateTime tool to provide date and time information
The dart://system-info resource to access system information
The dart://env-vars resource to access environment variables

You can test the connection by asking Claude to use one of these tools or access a resource.

Server Logging and Health Monitoring

Our MCP server includes logging and health monitoring features to help track its operation and troubleshoot issues.

Logging Configuration

// Set log level
_logger.setLevel(LogLevel.debug);

// Send log messages
server.sendLog(McpLogLevel.info, 'Flutter MCP Server started successfully');

Health Monitoring

The MCP server provides a health/check endpoint that returns information about its status:

final health = server.getHealth();
_logger.debug('Server is running: ${health.isRunning}');
_logger.debug('Connected sessions: ${health.connectedSessions}');
_logger.debug('Registered tools: ${health.registeredTools}');
_logger.debug('Uptime: ${health.uptime.inSeconds} seconds');

Extending the MCP Server

You can extend your MCP server in various ways to enhance its capabilities:

Adding New Tools

You can add new tools that interact with APIs or databases:

// Example weather API tool
server.addTool(
  name: 'weather',
  description: 'Get weather information for a specific city',
  inputSchema: {
    'type': 'object',
    'properties': {
      'city': {
        'type': 'string',
        'description': 'City name'
      }
    },
    'required': ['city']
  },
  handler: (args) async {
    final city = args['city'] as String;
    // Weather API call code...
    return CallToolResult([TextContent(text: 'Current temperature in New York: 22°C, Clear')]);
  },
);

File System Access

You can add resources that access the local file system:

// File system resource example
server.addResource(
  uri: 'file://{path}',
  name: 'File Resource',
  description: 'Access files on the system',
  mimeType: 'application/octet-stream',
  uriTemplate: {
    'type': 'object',
    'properties': {
      'path': {
        'type': 'string',
        'description': 'Path to the file'
      }
    }
  },
  handler: (uri, params) async {
    // File access code...
  }
);

Database Connections

You can create resources that connect to databases to provide information:

// Database resource example
server.addResource(
  uri: 'db://users/{id}',
  name: 'User Database',
  description: 'Access user information',
  mimeType: 'application/json',
  uriTemplate: {
    'type': 'object',
    'properties': {
      'id': {
        'type': 'string',
        'description': 'User ID'
      }
    }
  },
  handler: (uri, params) async {
    // Database access code...
  }
);

Conclusion

In this guide, we've implemented an MCP server using Flutter and Dart, and connected it to Claude Desktop. This allows Claude to interact with our local system, access resources, and use custom tools that we've defined.

By implementing the Model Context Protocol, you can significantly enhance the capabilities of AI models like Claude, enabling them to perform tasks that would otherwise be impossible due to their isolation from local systems.

As you continue to develop your MCP server, consider adding more tools and resources to expand its functionality. With the right implementation, you can create powerful AI-powered applications that combine the intelligence of large language models with the capabilities of your local system.

Learn More

Support This Work

If you found this tutorial helpful, please consider supporting the development of more free content like this through Patreon. Your support helps me create more high-quality developer tutorials and tools.

This is part of our ongoing series on AI development with Flutter. Stay tuned for more articles on advanced MCP implementations!

Flutter #Claude #AI #MCP #DartLang #ModelContextProtocol

DEV Community: MCP Dev Studio

Integrating AI with Flutter: Connecting Multiple LLM Providers to MCP Ecosystem

Introduction

Table of Contents

Integration Patterns for Different LLM Providers

Provider Characteristics

LlmCapability System and MCP Feature Mapping

Core Components of the LlmCapability System

Implementation of Capability Assessment

Provider-Specific MCP Tool Implementations

Implementation of Chat Methods

Handling Streaming Responses

Runtime Provider Switching

Setting Up the MCP Client

Executing Across Multiple Providers

Building the MultiProviderManager

Class Structure

Initialization and Setup

Setting Up LLM Clients for Different Providers

Smart Provider Selection

Provider Selection Logic

Smart Execution Implementation

Creating a Multi-Provider User Interface

Multi-Provider Chat Screen

Provider Status Display

Command Handling

Use Cases and Examples

1. Provider Comparison

2. Smart Provider Selection

Next Steps

Conclusion

Resources

Support the Developer

Integrating AI with Flutter: Creating AI Services with LlmServer and mcp_server

Introduction

Table of Contents

Understanding LlmServer and mcp_server

The Role of LlmServer

The Role of mcp_server

The Value of Integration

Server-Side Integration Architecture

Integration Model

Communication Flow

Setting Up the Integration

Registering LLM Functions as MCP Tools

1. Plugin Registration

2. Core LLM Plugins

Core LLM Plugins

AI-Based Tool Generation

Server Monitoring and Management

1. Logging System

2. Tool Inventory

3. Graceful Shutdown

Next Steps

Conclusion

Resources

Support the Developer

Integrating AI with Flutter: Building Powerful Apps with LlmClient and mcp_client

Introduction

Table of Contents

Understanding LlmClient and mcp_client

The Role of LlmClient

The Role of mcp_client

The Value of Integration

Integration Architecture

Integration Model

Communication Flow

Setting Up the Integration

Project Setup

Basic Integration Setup

Monitoring Connection State

Leveraging MCP Tools

Listing Available Tools

Indirect Tool Calls via AI

Direct Tool Calls

Handling Tool Calls in Streaming Responses

Working with MCP Resources

Listing Available Resources

Reading Resources

Using Resource Templates