AISDK MCP Bridge

AISDK MCP Bridge is a bridge package that enables seamless integration between Model Context Protocol (MCP) servers and AI SDK, allowing for efficient communication and tool execution between MCP servers and AI models. This documentation provides an in-depth guide on using the AISDK MCP Bridge, including installation, configuration, API reference, and debugging details.

Overview: What is AISDK MCP Bridge?

AISDK MCP Bridge serves as a crucial component that facilitates the connection between AI applications and various data sources or tools through the Model Context Protocol (MCP). By implementing this bridge, AI developers can ensure seamless interaction with different MCP servers, enhancing functionality and interoperability within their applications. This guide will cover how to set up and use AISDK MCP Bridge in your project.

🔧 Core Features & MCP Capabilities

AISDK MCP Bridge offers several key features that enhance the capabilities of MCP servers:

Seamless Integration

• AI SDK Compatibility: Seamlessly integrates with a wide range of AI applications, including Claude Desktop, Continue, Cursor, and more.
• Multi-Server Support: Supports multiple MCP server types such as Node.js, Python, UVX, and others.

Flexible Configuration

• Independent Server Configuration: Allows for independent configuration of each MCP server through mcp.config.json.
• TypeScript Support: Full TypeScript support with comprehensive type definitions.

Robust Error Handling & Logging

• Comprehensive error handling mechanisms ensure smooth operation even during unexpected issues.
• Detailed logging in both console output and the logs/mcp-tools.log file for debugging purposes.

⚙️ MCP Architecture & Protocol Implementation

AISDK MCP Bridge is built on top of the Model Context Protocol (MCP) architecture, providing a robust backbone for communication between AI applications and tools. The bridge implements key aspects of the MCP protocol, ensuring compatibility and seamless integration.

MCP Protocol Flow

The following Mermaid diagram illustrates the flow of an MCP interaction:

graph TD
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

MCP Client Compatibility Matrix

The AISDK MCP Bridge is designed to support a wide range of MCP clients, ensuring broad compatibility across different AI applications. Below is the MCP client compatibility matrix:

MCP Client	Resources	Tools	Prompts	Status
Claude Desktop	✅	✅	✅	Full Support
Continue	✅	✅	✅	Full Support
Cursor	❌	✅	❌	Tools Only

🚀 Getting Started with Installation

To get started using AISDK MCP Bridge, follow these steps:

1. Install the Package

   npm install aisdk-mcp-bridge
   

2. Configure MCP Servers Create an mcp.config.json file in your project root:

   {
     "mcpServers": {
       "twitter-mcp": {
         "command": "npx",
         "args": ["-y", "@enescinar/twitter-mcp"],
         "env": {
           "API_KEY": "your-twitter-api-key",
           "API_SECRET_KEY": "your-twitter-api-secret",
           "ACCESS_TOKEN": "your-twitter-access-token",
           "ACCESS_TOKEN_SECRET": "your-twitter-access-token-secret"
         }
       },
       "firecrawl": {
         "command": "npx",
         "args": ["-y", "mcp-server-firecrawl"],
         "env": {
           "FIRE_CRAWL_API_KEY": "your-firecrawl-api-key",
           "FIRE_CRAWL_API_URL": "https://api.firecrawl.com"
         }
       }
     }
   }
   

3. Import and Use the Bridge in Your Code

   import { generateText } from 'ai';
   import { google } from '@ai-sdk/google';
   import { getMcpTools, cleanupMcp, initializeMcp } from 'aisdk-mcp-bridge';
   import dotenv from 'dotenv';
   
   dotenv.config();
   
   async function main() {
     try {
       // Initialize MCP
       await initializeMcp({ debug: true });
   
       // Get tools from all servers
       const allTools = await getMcpTools({ debug: true });
   
       // Use the generated text and tools as needed
       const response = await generateText("What's the weather like today?");
       console.log(response);
   
     } catch (error) {
       console.error(error);
     }
   
     finally {
       // Clean up resources
       cleanupMcp();
     }
   }
   
   main();
   

💡 Key Use Cases in AI Workflows

Real-World Scenario 1: Weather Forecast Integration

In this scenario, an AI application can integrate with a weather data source using AISDK MCP Bridge. The application will fetch real-time weather information whenever a user asks about the current or next-day forecast.

graph TD
    A[User Query] --> B[MCP Client]
    B --> C[MCP Server]
    C --> D[Weather API]
    D --> E[Weather Data]
    E --> F[Integrated Application Display]

Real-World Scenario 2: Social Media Integration

Another use case involves integrating an AI application with a social media platform like Twitter to fetch tweets or post updates. This integration ensures that the application can utilize rich social media data in real-time.

graph TD
    A[User Interaction] --> B[MCP Client]
    B --> C[MCP Server]
    C --> D[Twitter API]
    D --> E[Tweets/Customer Feedback]
    E --> F[Integrated Application Actions]

🔌 Integration with MCP Clients

AISDK MCP Bridge ensures compatibility and seamless interaction with various MCP clients such as Claude Desktop, Continue, and Cursor. By leveraging the bridge, developers can build robust AI applications that provide users with a wide range of integrated tools and data sources.

Configuration Example

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@enescinar/twitter-mcp"],
      "env": {
        "API_KEY": "your-twitter-api-key",
        "API_SECRET_KEY": "your-twitter-api-secret",
        "ACCESS_TOKEN": "your-twitter-access-token",
        "ACCESS_TOKEN_SECRET": "your-twitter-access-token-secret"
      }
    },
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "mcp-server-firecrawl"],
      "env": {
        "FIRE_CRAWL_API_KEY": "your-firecrawl-api-key",
        "FIRE_CRAWL_API_URL": "https://api.firecrawl.com"
      }
    }
  }
}

📊 Performance & Compatibility Matrix

API Latency and Throughput

MCP Server	Latency (ms)	Throughput (requests/minute)
Twitter	<15	>200
FireCrawl	<5	N/A

Tool Compatibility

• Resource Tools: Fully integrated and compatible.
• Prompt Tools: Partially supported.

🛠️ Advanced Configuration & Security

AISDK MCP Bridge offers advanced configuration options to customize the bridge according to specific project requirements. Additionally, it includes security features to protect sensitive data during transmission.

Sample Configuration

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-twitter"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  },
  "securitySettings": {
    "encryptionKey": "your-encryption-key",
    "secureApiEndpoints": true
  }
}

❓ Frequently Asked Questions (FAQ)

Q1: How does the bridge handle MCP protocol errors?

A: The bridge includes detailed error handling mechanisms that log and propagate errors, ensuring that your application can gracefully handle exceptions.

Q2: Can I integrate multiple MCP servers simultaneously?

A: Yes, you can configure and use multiple MCP servers in parallel within a single project.

Q3: How do I ensure data privacy when using the bridge?

A: The bridge supports encryption for sensitive data. You can configure it to use secure API endpoints and manage encryption keys.

Q4: What tools does the bridge support by default?

A: By default, the bridge supports resource tools such as Twitter and FireCrawl.

Q5: How do I start using the bridge with an existing MCP server?

A: To integrate an existing MCP server, you need to specify the necessary configuration details in mcp.config.json and include the appropriate environment variables.

👨‍💻 Development & Contribution Guidelines

Contributions to AISDK MCP Bridge are welcome. Developers can help improve this library by contributing new features or fixing bugs. Follow these guidelines for submitting pull requests:

1. Fork the Repository
2. Create a New Branch
3. Make Changes and Add Tests
4. Commit and Push Changes
5. Open a Pull Request

For more information, visit the contribution guidelines.

🌐 MCP Ecosystem & Resources

Join the MCP community to stay informed about updates and contributions. The following resources are useful for developers working with MCP:

• MCP Documentation: Link
• GitHub Repository: aisdk-mcp-bridge GitHub Page
• Support and Issues: Issues Tracker

License

This project is licensed under the MIT License - see the LICENSE file for details.

By following this guide, developers can effectively integrate MCP servers into their AI applications, ensuring robust and efficient performance. If you have any further questions or need additional assistance, feel free to reach out through the available support channels.