4
MCP: Connect to External Systems

Use Model Context Protocol to give your agent access to any external system

Watch This Step Video

The Problem: Your Agent Lives in a Bubble

Your agent has memory and tools, but it's still isolated. It can't access your GitHub repos, your Slack channels, your databases, or any of the systems you actually use.

Without MCP

Build custom integrations for every service
Manage API keys and authentication
Write boilerplate for each external tool

With MCP

Plug-and-play external system access
Standardized integration protocol
Ready-made servers for popular services

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI models to securely access external data and tools. Think of it as USB for AI agents - a universal connector for any external system.

How MCP Works

1
MCP Server:Provides secure access to external resources (GitHub, databases, APIs, etc.)
2
MCP Client:Your VoltAgent connects to MCP servers to access their resources
3
Secure Access:All communication is authenticated and controlled by your permissions

Add MCP to Your Weather Agent

Let's upgrade your weather agent from the previous tutorial with file system access through MCP.

src/index.ts
import { VoltAgent, Agent, createTool, MCPConfiguration } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import path from "node:path";

// Your existing weather tool
const getWeatherTool = createTool({
name: "get_weather",
description: "Get current weather for any city",
parameters: z.object({
location: z.string().describe("City and state, e.g. New York, NY"),
}),
execute: async ({ location }) => {
console.log("Getting weather for " + location + "...");
if (location.toLowerCase().includes("new york")) {
return { temperature: "18°C", condition: "Partly cloudy" };
}
return { temperature: "24°C", condition: "Sunny" };
},
});

// NEW: Add MCP for file system access
const mcpConfig = new MCPConfiguration({
servers: {
filesystem: {
type: "stdio", // Connects via standard input/output
command: "npx", // The command to execute
args: [
// Arguments for the command
"-y",
"@modelcontextprotocol/server-filesystem", // Example: A filesystem server package
// Optional arguments for the server itself, like specifying allowed paths:
path.join(process.env.HOME || "", "Desktop"),
],
// Optional: Specify the working directory for the command
cwd: process.env.HOME,
// Optional: Request timeout in milliseconds (default: 30000)
timeout: 10000,
},
},
});

(async () => {
const tools = await mcpConfig.getTools();
const agent = new Agent({
name: "my-agent",
instructions: `You are a helpful assistant that can check weather and manage files. You can:
- Get weather information for any city
- Read and write files
- Save weather reports to files
- Manage data storage

Always be helpful and provide clear information.`,
llm: new VercelAIProvider(),
model: openai("gpt-4o-mini"),
tools: [
getWeatherTool,
...tools
],
});

new VoltAgent({
agents: { agent },
});
})();

// Now your agent can do both weather AND file operations!
// Try: "Check weather in London and save it to a file"
// Or: "What files are in the Desktop directory?"
// Or: "Read yesterday's weather report"

See MCP in Action

Here's what happens when your agent uses MCP filesystem tools in VoltOps console:

MCP Filesystem Demo

Watch your agent read files, create directories, and manage your filesystem through MCP:

MCP Filesystem Demo - Agent managing files through MCP in VoltOps

Real-time MCP filesystem operations: reading, writing, and managing files

What You're Seeing

In the demo above, the agent:

Connects to MCP filesystem server
Reads and writes files
Lists directory contents
Provides real-time feedback

HTTP MCP: Access AI Models & Remote Services

MCP isn't just for local files - it works over HTTP for remote services too. Let's connect your agent to Hugging Face's massive collection of AI models.

Setup: Get Your Hugging Face Token

1

Visit huggingface.co/settings/tokens

Create a free account if you don't have one

2

Click "New token" → Select "Read" access

Copy the token that starts with "hf_..."

3

Add to your .env file:

HUGGING_FACE_TOKEN=hf_your_token_here
Add HTTP MCP: Complete Agent with Both Local & Remote Tools
import { VoltAgent, Agent, createTool, MCPConfiguration } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import path from "node:path";

// Your existing weather tool (keep it!)
const getWeatherTool = createTool({
name: "get_weather",
description: "Get current weather for any city",
parameters: z.object({
location: z.string().describe("City and state, e.g. New York, NY"),
}),
execute: async ({ location }) => {
console.log("Getting weather for " + location + "...");
if (location.toLowerCase().includes("new york")) {
return { temperature: "18°C", condition: "Partly cloudy" };
}
return { temperature: "24°C", condition: "Sunny" };
},
});

// UPGRADE: Now we have BOTH local filesystem AND remote AI models!
const mcpConfig = new MCPConfiguration({
servers: {
// Local filesystem access (from previous example)
filesystem: {
type: "stdio",
command: "npx",
args: [
"-y",
"@modelcontextprotocol/server-filesystem",
path.join(process.env.HOME || "", "Desktop"),
],
cwd: process.env.HOME,
// Optional: Request timeout in milliseconds (default: 30000)
timeout: 10000,
},
// NEW: Remote Hugging Face AI models
"hf-mcp-server": {
url: "https://huggingface.co/mcp",
requestInit: {
headers: {
Authorization: `Bearer ${process.env.HUGGING_FACE_TOKEN}`
},
},
type: "http",
// Optional: Request timeout in milliseconds (default: 30000)
timeout: 30000,
},
},
});

(async () => {
try {
const tools = await mcpConfig.getTools();

const agent = new Agent({
name: "my-agent",
instructions: `You are a powerful assistant with comprehensive capabilities:

Weather Services:
- Get current weather for any city

File Management (Local MCP):
- Read and write files
- List directory contents
- Manage file storage
- Save weather reports to files

AI & ML Services (Remote MCP via Hugging Face):
- Generate images from text descriptions
- Analyze and classify images
- Process and understand text
- Translate between languages
- Answer questions about various topics

You can combine ALL these capabilities in creative ways!
Always explain what you're doing when using different tools.`,
llm: new VercelAIProvider(),
model: openai("gpt-4o-mini"),
tools: [
getWeatherTool, // Local weather tool
...tools // BOTH filesystem + AI tools
],
});

new VoltAgent({
agents: { agent },
});
} catch (error) {
console.error("Failed to initialize VoltAgent:", error);
}
})();

// Now your agent is a POWERHOUSE with weather + files + AI!
// Try these incredible combinations:
// "Check weather in Paris, generate an image of that weather, and save the report to a file"
// "Read my todo.txt file, translate it to Spanish, and generate an image for each task"
// "Create a weather report file for Tokyo with generated weather images"

Try These Amazing AI Combinations

Your agent now has access to thousands of AI models. Test these scenarios in VoltOps:

Weather + Image Generation:
What Makes This Incredible "Check weather in San Francisco and generate an image matching those conditions"
Weather + Translation:
"What's the weather in Barcelona? Also translate this to Spanish: 'It's a beautiful day!'"
Image Analysis + AI:
"Generate an image of a rainy day, then analyze what you see in that image"
Text Processing + Weather:
"Summarize this text and check the weather: 'I'm planning a trip to London next week...'"

HTTP MCP in Action: AI Models Demo

Watch your agent use both local filesystem and remote AI models through HTTP MCP:

HTTP MCP Hugging Face Demo - Agent using AI models and filesystem together

Powerful combination: Local file operations + Remote AI model access via HTTP MCP

What Makes This Incredible

In the demo above, you're seeing:

Local weather data retrieval
Remote AI image generation
File system write operations
Seamless tool coordination

AI Capabilities You Get

• Image generation from text
• Image analysis & classification
• Language translation
• Text summarization
• Question answering
• Sentiment analysis

Why This is Powerful

• Zero AI model hosting costs
• Access to latest models instantly
• Combine multiple AI capabilities
• Scale without infrastructure
• Mix local tools + remote AI
• Production-ready immediately

Explore the Complete MCP Directory

This is just a sample! VoltAgent maintains a growing directory of MCP servers with detailed setup instructions, code examples, and tool capabilities for each service.

10+ Ready-to-use servers with copy-paste configurations
Detailed tool listings showing exactly what each server can do
Live examples and implementation guides

What's Next?

You now have an agent that can access external systems through MCP. In the final tutorial, we'll learn about subagents - creating teams of specialized agents that work together.