Skip to main content

​
Overview

The lua mcp command manages Model Context Protocol (MCP) servers. Use it to list, activate, deactivate, and delete MCP servers.
MCP servers from integrations: When you connect a third-party account via lua integrations connect, an MCP server is automatically created and activated. These integration-based servers have a source field set to unifiedto. You can manage them with both lua mcp and lua integrations mcp commands.
lua mcp              # Interactive mode
lua mcp list         # List all servers
lua mcp activate     # Activate a server
lua mcp deactivate   # Deactivate a server
lua mcp delete       # Delete a server

​
Non-Interactive Mode

# List all MCP servers
lua mcp list

# Activate a server (positional or flag style)
lua mcp activate docs-server
lua mcp activate --server-name docs-server

# Deactivate a server
lua mcp deactivate --server-name api-server

# Delete a server
lua mcp delete --server-name old-server
OptionDescription
--server-name <name>MCP server name (for activate/deactivate/delete)
ActionDescriptionRequired Options
listList all MCP serversNone
activateActivate a server--server-name or positional
deactivateDeactivate a server--server-name or positional
deleteDelete a server--server-name or positional

​
Commands

​
lua mcp

Interactive MCP server management. 
lua mcp
Opens an interactive menu to:
  • List MCP servers
  • Activate a server
  • Deactivate a server
  • Delete a server

​
lua mcp list

List all MCP servers and their status. 
lua mcp list
# or
lua mcp ls
Output: 
============================================================
🔌 MCP Servers
============================================================

✅ Active Servers:

🟢 docs-server
   Transport: streamable-http
   URL: https://docs.example.com/mcp
   ID: mcp_abc123

────────────────────────────────────────

⏸️  Inactive Servers:

⚪ api-gateway
   Transport: streamable-http
   URL: https://api.example.com/mcp
   ID: mcp_def456

============================================================

​
lua mcp activate

Activate an MCP server to make its tools available. 
lua mcp activate              # Interactive selection
lua mcp activate docs-server  # Activate by name
# or
lua mcp enable docs-server    # Alias
What happens:
  • Server is marked as active
  • Server’s tools become available to your agent
  • Tools appear in the agent’s tool list at runtime
Example: 
$ lua mcp activate docs-server
🔄 Activating docs-server...

✅ MCP server "docs-server" activated successfully!

💡 The server's tools are now available to your agent.

​
lua mcp deactivate

Deactivate an MCP server to remove its tools. 
lua mcp deactivate              # Interactive selection
lua mcp deactivate docs-server  # Deactivate by name
# or
lua mcp disable docs-server     # Alias
What happens:
  • Server is marked as inactive
  • Server’s tools are removed from agent runtime
  • Configuration is preserved (can be re-activated)
Example: 
$ lua mcp deactivate docs-server
🔄 Deactivating docs-server...

✅ MCP server "docs-server" deactivated successfully!

💡 The server's tools are no longer available to your agent.

​
lua mcp delete

Permanently delete an MCP server. 
lua mcp delete              # Interactive selection
lua mcp delete docs-server  # Delete by name
# or
lua mcp rm docs-server      # Alias
This is permanent! Deleting an MCP server removes it from the platform. You’ll need to re-compile and push to recreate it.
Example: 
$ lua mcp delete docs-server

⚠️  You are about to delete MCP server: docs-server
⚠️  WARNING: This server is currently ACTIVE!
? Are you sure you want to delete this MCP server? (y/N) y

🔄 Deleting docs-server...

✅ MCP server "docs-server" deleted successfully!

​
Command Aliases

CommandAlias
lua mcp listlua mcp ls
lua mcp activatelua mcp enable
lua mcp deactivatelua mcp disable
lua mcp deletelua mcp rm

​
Pushing MCP Servers

MCP servers can also be pushed using the lua push command: 
# Push a single MCP server
lua push mcp
# Select server from list

# Push all components including MCP servers
lua push all --force
When pushing all with --auto-deploy, MCP servers are automatically activated: 
lua push all --force --auto-deploy

​
Workflow Example

1

Define MCP Server

Create the server in your code:
// src/mcp/docs.ts
import { LuaMCPServer, env } from 'lua-cli';

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

Add to Agent

// src/index.ts
import { LuaAgent } from 'lua-cli';
import { docsServer } from './mcp/docs';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  mcpServers: [docsServer]
});
3

Compile

lua compile
# Server is registered, ID assigned
4

Push

lua push mcp
# or
lua push all --force
5

Activate

lua mcp activate docs-server
# Tools are now available
6

Verify

lua mcp list
# Shows docs-server as active

​
Tips

Use lua mcp list to see current status before making changes
lua mcp list
# Shows which servers are active/inactive
Keep unused servers deactivated to reduce overhead
lua mcp activate docs-server    # When needed
lua mcp deactivate docs-server  # When done
In CI/CD, use lua push all --force to avoid prompts
lua push all --force --auto-deploy

lua compile

Compile and register MCP servers

lua push

Push MCP server configuration

​
See Also