MCP Server Migration: Complete Guide

This guide will help you migrate from wxflows to MCP (Model Context Protocol) servers for your LangGraph agent.

📋 Table of Contents

1. Prerequisites
2. Installation
3. File Structure
4. Step-by-Step Migration
5. Configuration
6. Testing
7. Deployment
8. Troubleshooting

Prerequisites

• Node.js 18+ installed
• TypeScript knowledge
• Existing wxflows-based LangGraph agent
• Google AI API key

Installation

1. Install Required Dependencies

npm install @modelcontextprotocol/sdk zod
<!-- /media/deep/D18/Projects/agent_langgraph/README.md -->

2. Update Your package.json

{
  "dependencies": {
    "@langchain/core": "^0.3.0",
    "@langchain/google-genai": "^0.1.0",
    "@langchain/langgraph": "^0.2.0",
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  }
}

3. Install Official MCP Servers (Optional)

# Install servers you want to use
npm install -g @modelcontextprotocol/server-weather
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-github

File Structure

Your new project structure should look like this:

your-project/
├── src/
│   ├── agent.ts              # Updated agent with MCP client
│   ├── langgraph.ts          # Updated workflow with initialization
│   ├── mcp-client.ts         # Production MCP client implementation
│   ├── mcp-config.ts         # Server configuration
│   ├── constants/
│   │   └── systemMessage.ts  # Your system message
│   └── servers/              # Custom MCP servers
│       └── mcp-server-example.ts
├── dist/                     # Compiled JavaScript
├── .env                      # Environment variables
├── package.json
└── tsconfig.json

Step-by-Step Migration

Step 1: Create MCP Client Files

Create three new files in your src/ directory:

1. mcp-client.ts - The production-ready MCP client (see artifact)
2. mcp-config.ts - Server configuration (see artifact)
3. mcp-server-example.ts - Template for custom servers (optional)

Step 2: Update agent.ts

Replace your wxflows imports and initialization:

BEFORE:

import wxflows from '@wxflows/sdk/langchain';

export const toolClient = new wxflows({
  endpoint: process.env.WXFLOWS_ENDPOINT || '',
  apikey: process.env.WXFLOWS_APIKEY,
});

export const tools = await toolClient.lcTools;
export const toolNode = new ToolNode(tools);

AFTER:

import { MCPClient } from './mcp-client';
import { getActiveServerConfigs, validateServerConfig } from './mcp-config';

export const mcpClient = new MCPClient();
let tools: DynamicStructuredTool[] = [];
let toolNode: ToolNode;

export async function initializeMCPTools() {
  const serverConfigs = getActiveServerConfigs();
  
  for (const [name, config] of Object.entries(serverConfigs)) {
    if (validateServerConfig(name, config)) {
      mcpClient.addServer(name, config);
    }
  }

  await mcpClient.initialize();
  tools = mcpClient.getTools();
  toolNode = new ToolNode(tools);
  
  return { tools, toolNode };
}

export { tools, toolNode };

Step 3: Update langgraph.ts

Add initialization check before processing messages:

let mcpInitialized = false;

async function ensureMCPInitialized() {
  if (!mcpInitialized) {
    console.log('🔧 Initializing MCP servers...');
    await initializeMCPTools();
    mcpInitialized = true;
    console.log('✅ MCP ready');
  }
}

export async function submitQuestion(messages: BaseMessage[], chatId: string) {
  // Initialize MCP tools if not already done
  await ensureMCPInitialized();
  
  // Rest of your code remains the same
  const optimizedMessages = optimizeMessages(messages);
  const workflow = createWorkflow();
  // ... etc
}

Step 4: Configure Your Servers

Edit mcp-config.ts to enable the servers you need:

export const ACTIVE_SERVERS = [
  'weather',        // Enable weather forecasting
  // 'filesystem',  // Uncomment to enable file operations
  // 'github',      // Uncomment for GitHub integration
  'custom',         // Your custom server
];

Step 5: Set Environment Variables

Create/update your .env file:

# Required
GOOGLE_API_KEY=your_google_api_key

# Optional - based on which servers you use
GITHUB_TOKEN=your_github_token
DATABASE_URL=postgresql://user:pass@localhost:5432/db
ALLOWED_DIRECTORY=/path/to/allowed/directory
SQLITE_DB_PATH=./database.sqlite

# Custom server variables
CUSTOM_API_KEY=your_api_key

Configuration

Adding Official MCP Servers

In mcp-config.ts, add servers to the MCP_SERVERS object:

export const MCP_SERVERS: Record<string, MCPServerConfig> = {
  weather: {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-weather'],
  },
  
  github: {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-github'],
    env: {
      GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN || '',
    },
  },
};

Creating Custom MCP Servers

Use the template in mcp-server-example.ts to create your own servers:

1. Define your tools:

const TOOLS = [
  {
    name: 'my_custom_tool',
    description: 'Does something useful',
    inputSchema: {
      type: 'object',
      properties: {
        param: { type: 'string', description: 'A parameter' },
      },
      required: ['param'],
    },
  },
];

1. Implement tool handlers:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  switch (name) {
    case 'my_custom_tool':
      const result = await myCustomFunction(args.param);
      return {
        content: [{ type: 'text', text: JSON.stringify(result) }],
      };
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});

1. Build and add to config:

# Compile your server
tsc src/servers/mcp-server-example.ts --outDir dist/servers

# Add to mcp-config.ts
export const MCP_SERVERS = {
  custom: {
    command: 'node',
    args: ['./dist/servers/mcp-server-example.js'],
  },
};

Testing

Test Individual Servers

Test servers work correctly before integration:

# Test weather server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  npx -y @modelcontextprotocol/server-weather

# Expected output: JSON with list of weather tools

Test Your Custom Server

# Build your server
npm run build

# Test it
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  node dist/servers/mcp-server-example.js

Test Full Integration

Create a simple test script test-mcp.ts:

import { initializeMCPTools } from './src/agent';

async function test() {
  console.log('Testing MCP integration...');
  
  const { tools } = await initializeMCPTools();
  
  console.log(`✅ Found ${tools.length} tools:`);
  tools.forEach(tool => {
    console.log(`  - ${tool.name}: ${tool.description}`);
  });
  
  process.exit(0);
}

test().catch(console.error);

Run it:

npx ts-node test-mcp.ts

Test with LangGraph

import { submitQuestion } from './src/langgraph';
import { HumanMessage } from '@langchain/core/messages';

async function testAgent() {
  const messages = [
    new HumanMessage('What is the weather in London?'),
  ];
  
  const stream = await submitQuestion(messages, 'test-chat-id');
  
  for await (const event of stream) {
    console.log(event);
  }
}

testAgent();

Deployment

Build Your Project

# Compile TypeScript
npm run build

# Or with watch mode during development
npm run dev

Production Considerations

1. Process Management: Use PM2 or similar to keep MCP servers running:

pm2 start dist/index.js --name "mcp-agent"

1. Error Handling: MCP client includes automatic restart capabilities:

// In your code
mcpClient.on('serverCrash', async (serverName) => {
  console.error(`Server ${serverName} crashed, restarting...`);
  await mcpClient.restartServer(serverName);
});

1. Monitoring: Check server status:

const status = getMCPStatus();
console.log('MCP Status:', status);
// Output: { weather: { connected: true, toolCount: 2 }, ... }

1. Graceful Shutdown: The MCP client handles cleanup automatically:

process.on('SIGTERM', () => {
  console.log('Shutting down...');
  mcpClient.shutdown();
  process.exit(0);
});

Troubleshooting

Common Issues and Solutions

1. "MCP client not initialized"

Problem: Trying to use tools before initialization.

Solution: Ensure initializeMCPTools() is called before submitQuestion():

await ensureMCPInitialized();

2. "Server failed to start"

Problem: MCP server process not spawning.

Solution:

• Check the command exists: which npx or which node
• Verify server package is installed
• Check environment variables are set
• Review server logs (stderr output)

3. "No tools found"

Problem: Tools not loading from server.

Solution:

• Test server independently (see Testing section)
• Check ACTIVE_SERVERS array includes your server
• Verify server is in MCP_SERVERS configuration
• Look for initialization errors in console

4. "Tool execution failed"

Problem: Tool runs but returns error.

Solution:

• Check input parameters match schema
• Verify API keys/credentials are set
• Review tool-specific requirements
• Check server stderr for detailed errors

5. "Server keeps crashing"

Problem: MCP server process exits unexpectedly.

Solution:

• Check server logs for errors
• Verify all required environment variables
• Test server independently
• Use restartServer() method to recover

6. "Tools work in test but not in agent"

Problem: Tools execute in isolation but fail in LangGraph.

Solution:

• Ensure toolNode is properly exported
• Verify tools array is populated before binding to LLM
• Check tool names don't conflict
• Review LangGraph workflow configuration

Debug Mode

Enable verbose logging:

// In mcp-client.ts, add more console.log statements
// Or set environment variable
process.env.DEBUG = 'mcp:*';

Getting Help

If you're still stuck:

1. Check server stderr output: 2>&1 | tee server.log
2. Review MCP specification: https://modelcontextprotocol.io
3. Test each component independently
4. Check GitHub issues for known problems

Migration Checklist

Use this checklist to track your migration progress:

• [ ] Install @modelcontextprotocol/sdk and zod
• [ ] Create mcp-client.ts with production client
• [ ] Create mcp-config.ts with server configurations
• [ ] Update agent.ts to use MCP client
• [ ] Update langgraph.ts with initialization check
• [ ] Configure ACTIVE_SERVERS in mcp-config
• [ ] Set required environment variables in .env
• [ ] Create custom MCP servers (if needed)
• [ ] Test individual servers work correctly
• [ ] Test full integration with test script
• [ ] Test agent with sample questions
• [ ] Build project successfully
• [ ] Test in staging environment
• [ ] Deploy to production
• [ ] Monitor for errors
• [ ] Document custom servers for your team

Next Steps

6.1 Conclusion

Project Summary:

This project migrated a LangGraph-based agent from the wxflows toolchain to an MCP (Model Context Protocol) server architecture. The goal was to replace tightly coupled tool integrations with a pluggable MCP client and server model, making tools easier to manage, test, and extend.

Key Achievements:

• Successfully scaffolded a minimal MCP client and configuration system that can discover and manage MCP servers.
• Updated the agent workflow to initialize MCP tools lazily and bind discovered tools into LangGraph's toolNode pattern.
• Added example server scaffolding and a RAG (retrieval-augmented generation) integration path for file-backed tool usage.
• Improved observability by adding structured logging points and clear troubleshooting steps in the README.

Challenges and Solutions:

• Challenge: Converting from a monolithic wxflows integration to a pluggable MCP architecture introduced bootstrapping order and initialization race conditions.

  • Solution: Implemented an ensureMCPInitialized() pattern that lazily initializes the MCP client before any workflow execution.

• Challenge: Tool schema and input expectations vary across servers (GraphQL vs RPC, different variable shapes).

  • Solution: Added explicit system prompt guidance and per-tool usage examples in the README; recommend documenting each custom server's schema and validating requests at the MCP server boundary.

• Challenge: Streaming and event handling differences (model streaming tokens vs tool call events) caused mismatches between agent output and the SSE frontend.

  • Solution: Normalized event handling in the API route to treat model chunks as strings and emit token events, and send full tool outputs on tool end events.

After successful migration:

1. Optimize Performance: Add caching, connection pooling
2. Add More Tools: Explore official MCP servers
3. Create Custom Servers: Build domain-specific tools
4. Monitor: Set up logging and alerting
5. Scale: Add load balancing if needed

Resources

• MCP Documentation
• MCP SDK GitHub
• Official MCP Servers
• LangChain Documentation
• LangGraph Documentation

---

Questions? Review the troubleshooting section or check the MCP documentation.