trackmcp
Back to directory
vrknetha

aisdk-mcp-bridge

View on GitHub

Bridge package enabling seamless integration between Model Context Protocol (MCP) servers and AI SDK tools. Supports multiple server types, real-time communication, and TypeScript.

22 stars TypeScriptAI & Machine Learning Updated Oct 11, 2025
aisdkfunctioncallingmcpmcp-servermodelcontextprotocoltoolcalling

Documentation

AISDK MCP Bridge

A bridge package that enables seamless integration between the Model Context Protocol (MCP) and AI SDK, allowing for efficient communication and tool execution between MCP servers and AI models.

npm version
License: MIT

Features

  • Seamless integration between MCP servers and AI SDK
  • Support for various MCP server types (Node.js, Python, UVX)
  • Multi-server support with independent configuration
  • Flexible configuration through `mcp.config.json`
  • TypeScript support with full type definitions
  • Robust error handling and logging
  • Easy-to-use API for tool execution

Installation

bash
npm install aisdk-mcp-bridge

Quick Start

1. Create an `mcp.config.json` file in your project root:

json
{
  "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"
      }
    }
  }
}

2. Import and use the bridge in your code:

typescript
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 });

    // Or get tools from a specific server
    const twitterTools = await getMcpTools({
      debug: true,
      serverName: 'twitter-mcp',
    });

    // Use tools with AI SDK
    const result = await generateText({
      model: google('gemini-1.5-pro'),
      messages: [
        {
          role: 'system',
          content:
            'You are an AI assistant that uses various tools to help users.',
        },
        {
          role: 'user',
          content: 'Your task description here',
        },
      ],
      tools: twitterTools, // or allTools for all available tools
    });

    console.log('Result:', result.text);
  } finally {
    // Clean up resources
    await cleanupMcp();
  }
}

main().catch(error => {
  console.error('Error:', error);
  process.exit(1);
});

Configuration

The `mcp.config.json` file supports multiple servers and communication modes. Each server can be configured independently.

Server Configuration Examples:

Twitter MCP Server

json
{
  "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 Server

json
{
  "mcpServers": {
    "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"
      }
    }
  }
}

SSE Server

json
{
  "mcpServers": {
    "sse-server": {
      "command": "node",
      "args": ["./server.js"],
      "mode": "sse",
      "sseOptions": {
        "endpoint": "http://localhost:3000/events",
        "headers": {},
        "reconnectTimeout": 5000
      }
    }
  }
}

Server Modes

The bridge supports different communication modes:

1. stdio Mode (Default)

    2. SSE Mode (Server-Sent Events)

      API Reference

      Core Functions

      `initializeMcp(options?: InitOptions): Promise`

      Initialize the MCP service with the provided options.

      typescript
      interface InitOptions {
        configPath?: string; // Path to mcp.config.json
        debug?: boolean; // Enable debug logging
      }

      `getMcpTools(options?: ToolOptions): Promise`

      Get AI SDK-compatible tools from MCP servers.

      typescript
      interface ToolOptions {
        debug?: boolean; // Enable debug logging
        serverName?: string; // Optional server name to get tools from a specific server
      }

      `executeMcpFunction(serverName: string, functionName: string, args: Record): Promise`

      Execute a specific function on an MCP server directly.

      typescript
      // Example
      const result = await executeMcpFunction('twitter-mcp', 'postTweet', {
        text: 'Hello from MCP!',
      });

      Core Types

      `MCPConfig` (alias for `MCPServersConfig`)

      Configuration type for MCP servers.

      typescript
      interface MCPConfig {
        mcpServers: {
          [key: string]: ServerConfig;
        };
      }

      `ServerConfig`

      Configuration for individual MCP servers.

      typescript
      interface ServerConfig {
        command: string;
        args?: string[];
        env?: Record;
        mode?: 'stdio' | 'sse';
        sseOptions?: {
          endpoint: string;
          headers?: Record;
          reconnectTimeout?: number;
        };
      }

      `MCPToolResult`

      Result type for MCP tool executions.

      typescript
      interface MCPToolResult {
        success: boolean;
        data?: unknown;
        error?: string;
      }

      `cleanupMcp(): Promise`

      Clean up MCP resources and close all server connections.

      Error Handling

      The bridge includes comprehensive error handling for:

      • Server initialization failures
      • Communication errors
      • Tool execution failures
      • Configuration issues
      • Server connection issues

      Logging

      The bridge provides detailed logging through:

      • `mcp-tools.log`: Server-side tool execution logs
      • Console output for debugging and errors

      Debug Logging

      You can enable detailed debug logging by setting the DEBUG environment variable:

      bash
      # Enable all debug logs
      DEBUG=* npm start
      
      # Enable MCP debug logs
      DEBUG=mcp npm start
      
      # Enable all MCP namespace logs
      DEBUG=mcp:* npm start

      Debug logs will show:

      • Server initialization and shutdown events
      • Tool registration and execution details
      • Communication with MCP servers
      • Schema conversions and validations
      • Error details with stack traces
      • Performance metrics and timing information

      Log Types

      The logging system supports three types of logs:

      • `info`: General operational information
      • `debug`: Detailed debugging information (requires DEBUG env variable)
      • `error`: Error messages and stack traces (always logged)

      Log File

      All logs are written to `logs/mcp-tools.log` with the following format:

      code
      [TIMESTAMP] [TYPE] Message
      {Optional JSON data}

      Development

      Prerequisites

      • Node.js 20.x or higher
      • npm 7.x or higher

      Setup

      1. Clone the repository

      2. Install dependencies:

      bash
      npm install

      Testing

      Run the test suite:

      bash
      npm test

      Run specific tests:

      bash
      npm run test:twitter
      npm run test:firecrawl

      Contributing

      We welcome contributions! Please see our Contributing Guide for details on:

      • Setting up the development environment
      • Coding standards
      • Pull request process
      • Adding new MCP servers

      Please note that this project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

      Support

      For support:

      1. Check the documentation

      2. Search existing issues

      3. Create a new issue if your problem persists

      Changelog

      See CHANGELOG.md for a list of changes and migration guides.

      Security

      For security issues, please email ravi@caw.tech instead of using the public issue tracker.

      Authors

      See also the list of contributors who participated in this project.

      Acknowledgments

      • AI SDK team for their excellent SDK
      • MCP community for the protocol specification
      • All contributors who have helped with the project

      License

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

      Frequently asked questions

      What is aisdk-mcp-bridge?

      aisdk-mcp-bridge is Bridge package enabling seamless integration between Model Context Protocol (MCP) servers and AI SDK tools. Supports multiple server types, real-time communication, and TypeScript.

      How do I install aisdk-mcp-bridge?

      Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

      Is aisdk-mcp-bridge open source?

      Yes — it is hosted on GitHub at https://github.com/vrknetha/aisdk-mcp-bridge and has 22 stars.

      Related MCP tools

      Run your own MCP server? See who uses it and what to fix.

      Measure it with TrackMCP