MCP Servers

What are MCP Servers?

MCP Servers are remote services 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 database queries, web searches, documentation access, 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 databases, web search, documentation access, and more

Mix & Match

Combine MCP servers with your custom LuaSkills

How MCP Servers Work

Configure Server

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

Compile & Push

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

Activate

Activate the server to make its tools available to your agent

Agent Uses Tools

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

Transport Types

MCP servers connect via HTTP-based transports:

Streamable HTTP (Recommended)
SSE (Legacy)

Modern MCP standard - Best for most use cases

Single endpoint for bidirectional communication
Supports session management and resumability
Works with all modern MCP servers

import { LuaMCPServer, env } from 'lua-cli';

const docsServer = new LuaMCPServer({
  name: 'docs',
  transport: 'streamable-http',
  url: 'https://mcp.example.com/mcp',
  headers: () => ({ 
    'Authorization': `Bearer ${env("MCP_API_TOKEN")}` 
  })
});

For older MCP servers that don’t support Streamable HTTP

Uses Server-Sent Events for server-to-client streaming
Separate endpoints for requests and events
Use when connecting to legacy MCP services

import { LuaMCPServer, env } from 'lua-cli';

const legacyServer = new LuaMCPServer({
  name: 'legacy-api',
  transport: 'sse',
  url: 'https://old-mcp.example.com/sse',
  headers: () => ({ 
    'Authorization': `Bearer ${env("API_KEY")}` 
  })
});

stdio transport not supported yet: Local MCP servers (using npx, node, etc.) are not supported yet. Please use remote MCP servers with streamable-http or sse transport instead.

Simple Example

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

// Connect to a remote MCP server
const docsServer = new LuaMCPServer({
  name: 'docs',
  transport: 'streamable-http',
  url: 'https://docs.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("DOCS_API_KEY")}`
  })
});

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

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

Common Use Cases

Documentation
APIs
Databases
Search

Access documentation and knowledge bases

import { LuaMCPServer, env } from 'lua-cli';

const docsServer = new LuaMCPServer({
  name: 'docs',
  transport: 'streamable-http',
  url: 'https://docs.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("DOCS_API_KEY")}`
  })
});

Tools provided vary by server:

search_docs - Search documentation
get_page - Get specific page content
list_sections - Browse documentation structure

Connect to API services

import { LuaMCPServer, env } from 'lua-cli';

const apiServer = new LuaMCPServer({
  name: 'my-api',
  transport: 'streamable-http',
  url: 'https://api.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("API_KEY")}`,
    'X-Api-Version': '2024-01'
  })
});

Connect to any MCP-compatible API service.

Query hosted database services

import { LuaMCPServer, env } from 'lua-cli';

const dbServer = new LuaMCPServer({
  name: 'database',
  transport: 'streamable-http',
  url: 'https://db-mcp.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("DB_API_KEY")}`
  })
});

Tools provided vary by server:

query - Execute queries
list_tables - Show tables
describe_table - Show schema

Web and content search

import { LuaMCPServer, env } from 'lua-cli';

const searchServer = new LuaMCPServer({
  name: 'search',
  transport: 'streamable-http',
  url: 'https://search-mcp.example.com/mcp',
  headers: () => ({
    'X-Api-Key': env("SEARCH_API_KEY")
  })
});

Tools provided vary by server:

web_search - Search the web
image_search - Search images
news_search - Search news

Environment Variables

MCP servers often need API keys or connection strings. Use the env() function to securely access environment variables at runtime:

Using env() (Recommended)
Static Values

Resolved at runtime from agent’s environment

import { LuaMCPServer, env } from 'lua-cli';

const apiServer = new LuaMCPServer({
  name: 'my-api',
  transport: 'streamable-http',
  url: 'https://api.example.com/mcp',
  headers: () => ({
    'Authorization': `Bearer ${env("API_TOKEN")}`,
    'X-Api-Key': env("API_KEY")
  })
});

Function is compiled and executed at runtime
Values come from lua env production settings
Consistent with env() in tool execute functions
Recommended for secrets and API keys

Stored directly in configuration

const apiServer = new LuaMCPServer({
  name: 'my-api',
  transport: 'streamable-http',
  url: 'https://api.example.com/mcp',
  headers: { 
    'X-Custom-Header': 'value',
    'Accept': 'application/json'
  }
});

Values are stored as-is in the database
Use only for non-sensitive configuration
Not recommended for secrets

Setting Environment Variables: Use lua env production to manage your agent’s environment variables. These are securely stored and made available to the env() function at runtime.

Dynamic URL with env()

You can also use env() to resolve the URL at runtime:

import { LuaMCPServer, env } from 'lua-cli';

const apiServer = new LuaMCPServer({
  name: 'my-api',
  transport: 'streamable-http',
  url: () => env("MCP_SERVER_URL"),
  headers: () => ({
    'Authorization': `Bearer ${env("API_TOKEN")}`
  })
});

MCP vs Custom Skills

Aspect	MCP Servers	LuaSkill
Code Required	None (just config)	Yes (TypeScript)
Customization	Limited to server options	Full control
Availability	Growing ecosystem	Unlimited
Best For	Standard integrations	Custom business logic

Best practice: Use MCP servers for standard integrations (docs, APIs, databases) and LuaSkill for custom business logic. They work great together!

Lifecycle

MCP servers have a simple lifecycle:

Define → Compile → Push → Activate → Use → Deactivate

1. Define

Create LuaMCPServer in your source code

2. Compile

Run lua compile - registers server and gets ID

3. Push

Run lua push mcp or lua push all --force - syncs configuration

4. Activate

Run lua mcp activate - makes tools available to agent

5. Use

Agent discovers and uses MCP server tools at runtime

6. Deactivate

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

Welcome

Build with AI

Key Concepts

Featured Demos

What are MCP Servers?

Think of it as:

Why MCP Servers?

No Code Required

Open Standard

Extend Capabilities

Mix & Match

How MCP Servers Work

Transport Types

Simple Example

Common Use Cases

Environment Variables

Dynamic URL with env()

MCP vs Custom Skills

Lifecycle

Managing MCP Servers

Next Steps

LuaMCPServer API

MCP Command

LuaAgent

Skills Concept

Welcome

Build with AI

Key Concepts

Featured Demos

​What are MCP Servers?

Think of it as:

​Why MCP Servers?

No Code Required

Open Standard

Extend Capabilities

Mix & Match

​How MCP Servers Work

​Transport Types

​Simple Example

​Common Use Cases

​Environment Variables

​Dynamic URL with env()

​MCP vs Custom Skills

​Lifecycle

​Managing MCP Servers

​Next Steps

LuaMCPServer API

MCP Command

LuaAgent

Skills Concept

What are MCP Servers?

Why MCP Servers?

How MCP Servers Work

Transport Types

Simple Example

Common Use Cases

Environment Variables

Dynamic URL with env()

MCP vs Custom Skills

Lifecycle

Managing MCP Servers

Next Steps