Skip to main content

​
What are MCP Servers?

MCP Servers are external processes that provide additional tools to your agent using the Model Context Protocol (MCP). Instead of building every tool from scratch, you can connect to existing MCP servers that provide file access, database queries, web searches, and more.

Think of it as:

Plug-and-play extensions for your agent - connect to pre-built tools without writing code
What is MCP? The Model Context Protocol is an open standard developed by Anthropic for connecting AI models to external tools and data sources. Learn more at modelcontextprotocol.io.

​
Why MCP Servers?

No Code Required

Use existing MCP servers - just configure and connect

Open Standard

MCP is an open protocol with a growing ecosystem

Extend Capabilities

Add file access, databases, web search, and more

Mix & Match

Combine MCP servers with your custom LuaSkills

​
How MCP Servers Work

1

Configure Server

Define the MCP server in your code with transport and connection details
2

Compile & Push

Run lua compile and lua push mcp to register with the platform
3

Activate

Activate the server to make its tools available to your agent
4

Agent Uses Tools

Your agent automatically discovers and uses the MCP server’s tools

​
Transport Types

MCP servers can run locally or remotely:
Run locally as a process
  • Uses stdin/stdout for communication
  • Great for npm packages and CLI tools
  • No network overhead
import { LuaMCPServer } from 'lua-cli';

const filesystemServer = new LuaMCPServer({
  name: 'filesystem',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/data']
});

​
Simple Example

import { LuaAgent, LuaMCPServer, LuaSkill } from 'lua-cli';

// Connect to filesystem MCP server
const filesystemServer = new LuaMCPServer({
  name: 'filesystem',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/data']
});

// Your custom skill
const coreSkill = new LuaSkill({
  name: 'core-skill',
  description: 'Core tools',
  tools: [...]
});

export const agent = new LuaAgent({
  name: 'file-assistant',
  persona: 'You are a helpful assistant with access to files.',
  skills: [coreSkill],
  
  // Add MCP server
  mcpServers: [filesystemServer]
});

​
Common Use Cases

Read and write files
const filesystemServer = new LuaMCPServer({
  name: 'filesystem',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/uploads']
});
Tools provided:
  • read_file - Read file contents
  • write_file - Write to files
  • list_directory - List files
  • search_files - Search by pattern

​
MCP vs Custom Skills

AspectMCP ServersLuaSkill
Code RequiredNone (just config)Yes (TypeScript)
CustomizationLimited to server optionsFull control
AvailabilityGrowing ecosystemUnlimited
Best ForStandard integrationsCustom business logic
Best practice: Use MCP servers for standard integrations (files, search, databases) and LuaSkill for custom business logic. They work great together!

​
Lifecycle

MCP servers have a simple lifecycle: 
Define → Compile → Push → Activate → Use → Deactivate
Create LuaMCPServer in your source code
Run lua compile - registers server and gets ID
Run lua push mcp or lua push all --force - syncs configuration
Run lua mcp activate - makes tools available to agent
Agent discovers and uses MCP server tools at runtime
Run lua mcp deactivate - removes tools from agent

​
Managing MCP Servers

Use the lua mcp command to manage servers: 
lua mcp list        # List all MCP servers and their status
lua mcp activate    # Activate a server (make tools available)
lua mcp deactivate  # Deactivate a server (remove tools)
lua mcp delete      # Delete a server from the platform

​
Next Steps

LuaMCPServer API

Complete API reference and examples

MCP Command

CLI commands for managing servers

LuaAgent

Adding MCP servers to your agent

Skills Concept

Custom tools with LuaSkill