aisdk-mcp-bridge
Bridge package enabling seamless integration between Model Context Protocol (MCP) servers and AI SDK tools. Supports multiple server types, real-time communication, and TypeScript.
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.
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
npm install aisdk-mcp-bridgeQuick Start
1. 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"
}
}
}
}2. 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 });
// 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
{
"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
{
"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
{
"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.
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.
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.
// Example
const result = await executeMcpFunction('twitter-mcp', 'postTweet', {
text: 'Hello from MCP!',
});Core Types
`MCPConfig` (alias for `MCPServersConfig`)
Configuration type for MCP servers.
interface MCPConfig {
mcpServers: {
[key: string]: ServerConfig;
};
}`ServerConfig`
Configuration for individual MCP servers.
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.
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:
# Enable all debug logs
DEBUG=* npm start
# Enable MCP debug logs
DEBUG=mcp npm start
# Enable all MCP namespace logs
DEBUG=mcp:* npm startDebug 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:
[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:
npm installTesting
Run the test suite:
npm testRun specific tests:
npm run test:twitter
npm run test:firecrawlContributing
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
- Ravi Kiran - _Initial work_ - @vrknetha
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
A Unified MCP Server Management App TypeScript-based implementation. Trusted by 800+ developers. Trusted by 800+ developers.
A powerful VSCode extension that lets you find and install MCP servers to use with GitHub Copilot.. TypeScript-based implementation.
A Minecraft MCP Server powered by Mineflayer API. It allows to control a Minecraft character in real-time, allowing AI assistants to build structures, explor...
AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Ag...
🤖 A visualization mcp contains 25+ visual charts using @antvis. Using for chart generation and data analysis. TypeScript-based implementation.
🚀MCP server for accessing RedNote(XiaoHongShu, xhs). TypeScript-based implementation. Trusted by 800+ developers. Trusted by 800+ developers.
Run your own MCP server? See who uses it and what to fix.
Measure it with TrackMCP