How an MCP server is attached
You declare the server withLuaMCPServer and register it on the agent’s mcpServers:
src/mcp/docs.mcp.ts
streamable-http, the current MCP standard with a single endpoint, and sse for older servers. A stdio transport (a local process started with npx or node) is not supported, and the constructor throws if you pass it. url and headers accept a function as well as a value; a function runs on the platform when the server’s configuration is built (its result is cached for a few minutes), so env() inside it reads the agent’s environment and the secret never lands in configuration. timeout is in milliseconds; leave it unset and the platform’s own 60-second client timeout applies.
The lifecycle differs from versioned primitives. lua push mcp registers the server on the platform by name, or updates the record with the same name; there are no versions, and nothing changes for end users yet. lua mcp activate <name> activates it: the agent connects, lists the server’s tools, and the model can call them on its next turn, in production. lua mcp deactivate <name> removes the tools again, and lua mcp delete <name> removes the record. lua mcp list shows every server and its state. Because activation changes the live agent, treat it like a deploy; lua push mcp --auto-deploy pushes and activates in one step.
Nothing in the CLI lists the tools a server contributed. lua mcp list prints each server’s name, transport, URL, ID, and whether it is active; the platform discovers the tools when a conversation needs them, server by server, each with a time budget. A server that fails discovery contributes no tools for that turn and the rest of the agent carries on, so a successful activation proves the record, not the connection. To confirm the tools are there before end users hit them, ask the agent in lua chat for something only that server can do, then read lua logs --type mcp: every call the model makes is logged with the server name and the tool name.
Servers provided by integrations are managed separately. Connecting a Unified.to integration provisions an MCP server for that connection; you list, activate, and deactivate those with lua integrations mcp list|activate|deactivate --connection <id>, and you should not hand-write a LuaMCPServer for a SaaS the catalog covers.
The docs MCP you connect to Cursor or Claude Code is a different thing: it serves this documentation to the coding tool while you build and has nothing to do with your agent’s runtime. See Docs MCP.
MCP servers and skills
A skill is tools you write, versioned and deployed with your agent, with acontext that tells the model when to use them. An MCP server is tools someone else wrote, discovered at runtime, with descriptions you do not control. Use an MCP server when the operations already exist behind MCP; use a skill when you need custom logic, your own descriptions, or a tool the model should see only under a condition. An integration is a third option: a connection to a known SaaS that provisions its MCP server for you and adds events and raw API access.
When to use it
- A vendor or an internal team ships an MCP server for the system you need: attach it.
- The SaaS is listed by
lua integrations available: connect the integration instead; it provisions the MCP server and handles authentication. - You need one operation with your own validation or description: write a tool.
- The server runs only as a local process: not supported; host it behind HTTP first.
Limits
Next steps
Use an MCP server
Attach, push, activate, and verify the tools in a chat.
LuaMCPServer reference
Every configuration field.
lua mcp
List, activate, deactivate, and delete servers.
About integrations
Integrations that provision their own MCP servers.