LuaMCPServer

LuaMCPServer declares a remote MCP server whose tools the model can call alongside your skills. Register instances on LuaAgent under mcpServers, push them with lua push mcp, and activate them with lua mcp activate. Only remote servers over streamable-http or sse are supported; stdio is not. A LuaMCPServer suits a server whose configuration belongs in your project, with headers read from the agent’s environment. For a server that signs in with OAuth, or one the people running the agent should manage themselves, add it by URL from the Tools page instead: see Add a custom MCP server. A server added that way isn’t part of your project, and lua push never overwrites it. Verified against lua-cli 3.33.0.

import { LuaMCPServer } from 'lua-cli';

Quick example

A Streamable HTTP server whose Authorization header is read from the agent’s environment at runtime:

src/mcp/DocsServer.ts

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

export default new LuaMCPServer({
  name: 'docs',
  transport: 'streamable-http',
  url: 'https://mcp.example.com/mcp',
  headers: () => ({ Authorization: `Bearer ${env('DOCS_MCP_TOKEN')}` }),
  timeout: 30000,
});

Constructor

Creates an MCP server declaration from a LuaMCPServerConfig.

new LuaMCPServer(config: LuaMCPServerConfig): LuaMCPServer

Errors

MCP server name is required when name is empty.
stdio transport is not supported yet. Please use 'streamable-http' (recommended) or 'sse' transport instead. … when transport is 'stdio'.
URL is required for <transport> transport when url is missing.

Configuration

The config has five fields. There is no description field.

string

required

Server-side identifier, and the name lua push mcp --name and lua mcp activate address. Kebab-case, for example docs. The model sees the server’s tools as <name>_<tool>.

'streamable-http' | 'sse'

required

'streamable-http' is the MCP standard transport; use it wherever the server supports it. 'sse' is the legacy Server-Sent Events transport for servers that do not.

string | (() => string)

required

The server endpoint. A function is evaluated in the deployed runtime when the server is connected, so env() works inside it: url: () => env('MCP_SERVER_URL') ?? 'https://mcp.example.com/mcp'.

Record<string, string> | (() => Record<string, string>)

Headers sent with every request. A function is evaluated at connection time like url; a static object is stored verbatim in the pushed version, so put secrets behind env() in a function.

number

default:60000

Timeout in milliseconds for each request to the server, tool calls included. Tool discovery runs under a separate platform budget of a few seconds per server, so a larger value doesn’t extend discovery.

Instance methods

Method	Returns
`getName()`	`string`
`getTransport()`	`MCPTransport`
`getTimeout()`	`number \| undefined`, as configured
`getConfig()`	The `LuaMCPServerConfig` passed to the constructor
`toJSON()`	`{ name, transport, url, headers?, timeout? }`; function-valued `url` and `headers` are kept as functions

Lifecycle

lua push mcp --name <name> creates or updates the server on the agent and records its id in lua.skill.yaml. MCP servers are not versioned: lua deploy has no mcp type, and a push replaces the configuration in place.
A pushed server starts inactive. lua mcp activate <name> exposes its tools to the model; lua push mcp --auto-deploy activates in the same command. lua mcp deactivate <name> hides them again without deleting the server.
Tools are discovered from the server, cached by the platform, and offered to the model as <name>_<tool>.
lua mcp list shows every server on the agent, grouped by who manages it, with its state; lua mcp delete <name> removes one of yours. Servers from integrations or the Tools page are listed but not changed by lua mcp.

Types

All of these are exported from 'lua-cli'.

type MCPTransport = 'sse' | 'streamable-http';

interface MCPServerBaseConfig {
  name: string;
  timeout?: number;
}

interface MCPStreamableHttpServerConfig extends MCPServerBaseConfig {
  transport: 'streamable-http';
  url: string | (() => string);
  headers?: Record<string, string> | (() => Record<string, string>);
}

interface MCPSSEServerConfig extends MCPServerBaseConfig {
  transport: 'sse';
  url: string | (() => string);
  headers?: Record<string, string> | (() => Record<string, string>);
}

type LuaMCPServerConfig = MCPSSEServerConfig | MCPStreamableHttpServerConfig;

SDK

CLI

REST API

Quick example

Constructor

Configuration

Instance methods

Lifecycle

Types

See also

​Quick example

​Constructor

​Configuration

​Instance methods

​Lifecycle

​Types

​See also

Quick example

Constructor

Configuration

Instance methods

Lifecycle

Types

See also