> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LuaMCPServer

> A remote MCP server whose tools the agent can call, attached by URL over Streamable HTTP or SSE

`LuaMCPServer` declares a remote [MCP server](https://docs.heylua.ai/concepts/mcp-servers.md) whose tools the model can call alongside your skills. Register instances on [`LuaAgent`](https://docs.heylua.ai/reference/sdk/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](https://docs.heylua.ai/integrations/custom-mcp-servers.md). A server added that way isn't part of your project, and `lua push` never overwrites it.

*Verified against lua-cli 3.33.0.*

```ts theme={null}
import { LuaMCPServer } from 'lua-cli';
```

## Quick example

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

```ts src/mcp/DocsServer.ts theme={null}
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`.

```ts theme={null}
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.

**name** `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>`.

**transport** `'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.

**url** `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'`.

**headers** `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.

**timeout** `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'`.

```ts theme={null}
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;
```

## See also

* [MCP servers](https://docs.heylua.ai/concepts/mcp-servers.md) — attach, push, activate; integration-provided servers
* [Use an MCP server](https://docs.heylua.ai/build/use-an-mcp-server.md) — how-to
* [`lua mcp`](https://docs.heylua.ai/reference/cli/mcp) — list, activate, deactivate, delete
* [`env`](https://docs.heylua.ai/reference/sdk/env) — reading secrets inside `url` and `headers` resolvers
* [`LuaAgent`](https://docs.heylua.ai/reference/sdk/luaagent) — the `mcpServers` field


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.