LuaMCPServer

Overview

LuaMCPServer allows you to connect external MCP (Model Context Protocol) servers to your agent. MCP servers provide additional tools that your agent can use at runtime, enabling integration with file systems, databases, APIs, and more.

import { LuaMCPServer } from 'lua-cli';

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

export default filesystemServer;

What is MCP? The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. Learn more at modelcontextprotocol.io.

Why MCP Servers?

Extend Capabilities

Add tools without writing code - use existing MCP servers

Standard Protocol

Compatible with any MCP-compliant server

Local or Remote

Run servers locally (stdio) or connect to remote endpoints (SSE)

Community Ecosystem

Access growing library of community MCP servers

Transport Types

MCP servers support two transport methods:

stdio (Local)
sse (Remote)

Best for: Local execution, npm packages, CLI toolsThe server runs as a local process. Your agent communicates via stdin/stdout.

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

Best for: Remote servers, hosted services, APIsThe server runs remotely. Your agent connects via Server-Sent Events (SSE).

const remoteServer = new LuaMCPServer({
  name: 'docs-server',
  transport: 'sse',
  url: 'https://mcp.example.com/sse',
  headers: {
    'Authorization': 'Bearer my-api-key'
  }
});

Constructor

new LuaMCPServer(config)

Creates a new MCP server configuration.

config

LuaMCPServerConfig

required

MCP server configuration object

Configuration Parameters

Required Fields

name

string

required

Unique identifier for the MCP serverFormat: lowercase, hyphens allowedExamples: 'filesystem', 'github-server', 'database'

transport

'stdio' | 'sse'

required

Transport protocol for communication

'stdio' - Local process via stdin/stdout
'sse' - Remote server via Server-Sent Events

stdio Transport Fields

command

string

Command to execute the MCP serverRequired when: transport: 'stdio'Examples: 'npx', 'node', 'python'

args

string[]

Arguments to pass to the commandExample: ['-y', '@modelcontextprotocol/server-filesystem', '/data']

env

Record<string, string>

Environment variables for the server processExample: { 'API_KEY': 'secret123' }

SSE Transport Fields

url

string

URL of the remote MCP serverRequired when: transport: 'sse'Example: 'https://mcp.example.com/sse'

headers

Record<string, string>

HTTP headers to send with requestsExample: { 'Authorization': 'Bearer token' }

Optional Fields

timeout

number

Timeout in milliseconds for server operationsDefault: 60000 (60 seconds)

Examples

Filesystem Access

import { LuaMCPServer } from 'lua-cli';

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

export default filesystemServer;

GitHub Integration

import { LuaMCPServer } from 'lua-cli';

const githubServer = new LuaMCPServer({
  name: 'github',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-github'],
  env: {
    'GITHUB_PERSONAL_ACCESS_TOKEN': 'ghp_xxxx'
  }
});

export default githubServer;

Remote Database Server

import { LuaMCPServer } from 'lua-cli';

const databaseServer = new LuaMCPServer({
  name: 'database',
  transport: 'sse',
  url: 'https://db-mcp.example.com/sse',
  headers: {
    'Authorization': 'Bearer db-api-key',
    'X-Database': 'production'
  },
  timeout: 45000
});

export default databaseServer;

Brave Search

import { LuaMCPServer } from 'lua-cli';

const braveSearch = new LuaMCPServer({
  name: 'brave-search',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@anthropic/mcp-server-brave-search'],
  env: {
    'BRAVE_API_KEY': 'your-brave-api-key'
  }
});

export default braveSearch;

Using with LuaAgent

MCP servers are added to your agent configuration:

import { LuaAgent, LuaSkill } from 'lua-cli';
import filesystemServer from './mcp/filesystem';
import githubServer from './mcp/github';

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

export const agent = new LuaAgent({
  name: 'enhanced-agent',
  persona: 'You are an assistant with access to files and GitHub.',
  skills: [coreSkill],
  
  // Add MCP servers
  mcpServers: [
    filesystemServer,
    githubServer
  ]
});

Lifecycle Management

Compile

During lua compile, MCP servers are:

Detected from your source code
Registered with the server (if new)
Assigned an ID stored in lua.skill.yaml
Configuration written to dist/mcp-servers.json

Push

Push individual MCP server:

lua push mcp
# Select server from list

Or push all components:

lua push all --force

Activate / Deactivate

MCP servers start inactive. Activate to make tools available:

lua mcp activate
# Select server to activate

lua mcp deactivate
# Select server to deactivate

List / Delete

lua mcp list              # Show all MCP servers
lua mcp delete            # Remove an MCP server

YAML Configuration

After compilation, lua.skill.yaml tracks MCP servers:

agent:
  agentId: your-agent-id
  persona: ...

mcpServers:
  - name: filesystem
    mcpServerId: mcp_abc123
  - name: github
    mcpServerId: mcp_def456

The YAML only stores name and mcpServerId. The full configuration (command, args, url, etc.) lives in your source code.

Best Practices

✅ Use Environment Variables for Secrets

Never hardcode API keys or tokens

// ✅ Good
env: {
  'GITHUB_TOKEN': process.env.GITHUB_TOKEN
}

// ❌ Bad
env: {
  'GITHUB_TOKEN': 'ghp_hardcoded_token'
}

✅ Set Appropriate Timeouts

Adjust timeout based on expected operation duration

// Quick operations
timeout: 10000  // 10 seconds

// Database queries
timeout: 30000  // 30 seconds

// File processing
timeout: 120000 // 2 minutes

✅ Restrict Paths for Filesystem Access

Only expose necessary directories

// ✅ Specific allowed path
args: ['-y', '@modelcontextprotocol/server-filesystem', '/app/uploads']

// ❌ Too permissive
args: ['-y', '@modelcontextprotocol/server-filesystem', '/']

✅ Activate Only What You Need

Keep unused servers deactivated to reduce overhead

# Activate only when needed
lua mcp activate github-server

# Deactivate when done
lua mcp deactivate github-server

Popular MCP Servers

Server	Description	Install
Filesystem	Read/write local files	`@modelcontextprotocol/server-filesystem`
GitHub	GitHub API integration	`@modelcontextprotocol/server-github`
Brave Search	Web search via Brave	`@anthropic/mcp-server-brave-search`
SQLite	SQLite database access	`@modelcontextprotocol/server-sqlite`
Postgres	PostgreSQL database	`@modelcontextprotocol/server-postgres`
Google Drive	Google Drive files	`@anthropic/mcp-server-gdrive`

Check modelcontextprotocol.io/servers for the full list of available MCP servers.

Troubleshooting

Server not found after push

Make sure the server is activated:

lua mcp list      # Check status
lua mcp activate  # Activate if needed

Command not found (stdio)

Ensure the command is installed and in PATH:

# Test the command directly
npx -y @modelcontextprotocol/server-filesystem --help

Connection timeout (sse)

Check the URL is accessible and increase timeout:

const server = new LuaMCPServer({
  transport: 'sse',
  url: 'https://...',
  timeout: 120000  // Increase timeout
});

Authentication failed

Verify your API key or token is correct:

headers: {
  'Authorization': `Bearer ${process.env.MCP_API_KEY}`
}

LuaAgent

Agent configuration with MCP servers

LuaSkill

Custom tool collections

Environment

Managing environment variables

MCP Command

CLI management commands

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Overview

Why MCP Servers?

Extend Capabilities

Standard Protocol

Local or Remote

Community Ecosystem

Transport Types

Constructor

new LuaMCPServer(config)

Configuration Parameters

Required Fields

stdio Transport Fields

SSE Transport Fields

Optional Fields

Examples

Filesystem Access

GitHub Integration

Remote Database Server

Brave Search

Using with LuaAgent

Lifecycle Management

Compile

Push

Activate / Deactivate

List / Delete

YAML Configuration

Best Practices

Popular MCP Servers

Troubleshooting

LuaAgent

LuaSkill

Environment

MCP Command

See Also

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

​Overview

​Why MCP Servers?

Extend Capabilities

Standard Protocol

Local or Remote

Community Ecosystem

​Transport Types

​Constructor

​new LuaMCPServer(config)

​Configuration Parameters

​Required Fields

​stdio Transport Fields

​SSE Transport Fields

​Optional Fields

​Examples

​Filesystem Access

​GitHub Integration

​Remote Database Server

​Brave Search

​Using with LuaAgent

​Lifecycle Management

​Compile

​Push

​Activate / Deactivate

​List / Delete

​YAML Configuration

​Best Practices

​Popular MCP Servers

​Troubleshooting

​Related APIs

LuaAgent

LuaSkill

Environment

MCP Command

​See Also

Overview

Why MCP Servers?

Transport Types

Constructor

new LuaMCPServer(config)

Configuration Parameters

Required Fields

stdio Transport Fields

SSE Transport Fields

Optional Fields

Examples

Filesystem Access

GitHub Integration

Remote Database Server

Brave Search

Using with LuaAgent

Lifecycle Management

Compile

Push

Activate / Deactivate

List / Delete

YAML Configuration

Best Practices

Popular MCP Servers

Troubleshooting

Related APIs

See Also