MCP Setup for AI Agents

Reading with an LLM? Give it this page as Markdown: http://localhost/docs/agents/mcp-setup.md

NoLag provides a Model Context Protocol (MCP) server that lets AI agents manage your real-time infrastructure directly. Connect Claude Desktop, Cursor, or any MCP-compatible client to create apps, rooms, actors, publish messages, and dispatch tasks, all through natural language.

Prerequisites. You need a NoLag account with a project-scoped API key. Create one in the Portal: open your project and go to API Keys. The secret half is shown once.

Quick Start

Create a project in the NoLag Portal
Generate a project-scoped API key (format: nlg_live_yourKeyId.yourSecret)
Add the NoLag MCP server to your AI client's configuration (see below)
Ask your AI agent to "list my NoLag apps" or "create an agent actor" to verify

Claude Desktop / Claude Code

Add this to your configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows for Claude Desktop, or .mcp.json in your project root for Claude Code):

{
  "mcpServers": {
    "nolag": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.nolag.app/mcp/sse?token=nlg_live_yourKeyId.yourSecret"
      ]
    }
  }
}

Replace nlg_live_yourKeyId.yourSecret with your actual API key.

Note. mcp-remote is a third-party npm package that bridges the SSE transport to stdio for clients that only speak stdio. npx installs it on first run.

Cursor

Add this to your Cursor MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "nolag": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.nolag.app/mcp/sse?token=nlg_live_yourKeyId.yourSecret"
      ]
    }
  }
}

Custom MCP Clients (HTTP)

NoLag supports both SSE transport (GET /mcp/sse, with tool calls posted to the /mcp/message URL the stream announces) and plain HTTP (POST /mcp) for MCP. Use SSE for streaming clients; use HTTP for simple request/response integrations.

The handshake and the tool catalog are public. Only tools/call needs your key.

# Initialize session (no key needed)
curl -X POST https://api.nolag.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {}
  }'

# List available tools (no key needed)
curl -X POST https://api.nolag.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/list",
    "params": {}
  }'

# Create an agent actor (key required)
curl -X POST https://api.nolag.app/mcp \
  -H "Authorization: Bearer nlg_live_yourKeyId.yourSecret" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "nolag_create_agent",
      "arguments": {
        "name": "my-first-agent",
        "capabilities": ["drafting", "research"]
      }
    }
  }'

Transports

Transport	Endpoint	Auth	Use Case
SSE via mcp-remote (recommended)	`GET /mcp/sse`, then `POST /mcp/message?sessionId=...`	`?token=` query parameter or `Authorization` header	Claude Desktop, Claude Code, Cursor, and other MCP clients
HTTP	`POST /mcp`	`Authorization` header	Simple integrations, scripts, testing

Available Tools

The NoLag MCP server exposes 35 tools for managing your real-time infrastructure:

App Management

Tool	Description
`nolag_list_apps`	List all apps in your project
`nolag_create_app`	Create a new app (optionally from a blueprint)
`nolag_get_app`	Get details about a specific app
`nolag_update_app`	Update an app's name or description
`nolag_delete_app`	Soft-delete an app

Room Management

Tool	Description
`nolag_list_rooms`	List all rooms in an app
`nolag_create_room`	Create a new dynamic room
`nolag_get_room`	Get room details
`nolag_update_room`	Update a room
`nolag_delete_room`	Delete a dynamic room (static rooms cannot be deleted)

Actor Management

Tool	Description
`nolag_list_actors`	List all actors in your project
`nolag_create_actor`	Create a new actor (device, user, service, agent, etc.)
`nolag_get_actor`	Get actor details
`nolag_update_actor`	Update an actor
`nolag_delete_actor`	Delete an actor

Agent-Specific

Tool	Description
`nolag_create_agent`	Create an AI agent actor with a persistent session and capability tags
`nolag_create_orchestrator`	Create an orchestrator actor for coordinating agents
`nolag_create_agents_app`	Create an app from the Agents blueprint
`nolag_dispatch_task`	Publish a task envelope to a room's tasks topic
`nolag_list_agent_events`	Query the agent event stream with severity/category filters
`nolag_get_blackboard_state`	Read the current shared state for a room

Messaging

Tool	Description
`nolag_publish`	Publish a message to a room/topic
`nolag_get_messages`	Get recent messages from a room/topic

Scopes

Tool	Description
`nolag_create_scope`	Create an access scope for tenant isolation
`nolag_list_scopes`	List all access scopes in the project
`nolag_get_scope`	Get details about a specific access scope
`nolag_update_scope`	Update a scope's name, description, metadata, or active flag (the slug cannot change)
`nolag_delete_scope`	Delete a scope (fails while actors are still assigned to it)
`nolag_list_scope_actors`	List the actors assigned to a scope
`nolag_set_actor_scope`	Assign an actor to a scope or unscope them

Webhooks

Tool	Description
`nolag_configure_webhooks`	Configure hydration and trigger webhooks for an app
`nolag_get_webhook_config`	Get current webhook configuration
`nolag_list_webhook_dlq`	List failed webhook requests
`nolag_retry_webhook_dlq`	Retry a failed webhook

Code Generation

Tool	Description
`nolag_generate_code`	Generate SDK client code for a specific use case

Authentication

initialize, notifications/initialized, ping, and tools/list are served without a key, so any client or directory can introspect the server. tools/call requires a project-scoped API key. Organization-level and system keys are rejected. There are two ways to send the key:

Option 1: Authorization Header (recommended)

Works on every endpoint.

Authorization: Bearer nlg_live_yourKeyId.yourSecret

Option 2: Query Parameter (SSE transport only)

GET /mcp/sse and POST /mcp/message also read the key from a ?token= query parameter, for clients such as mcp-remote that cannot set custom headers. POST /mcp does not; it reads the header only.

https://api.nolag.app/mcp/sse?token=nlg_live_yourKeyId.yourSecret

Security. Your API key grants full project access. Never expose it in client-side code or public repositories.

Agent Workflow Example

Here is a typical workflow using MCP to set up a multi-agent system:

Create an agents app: nolag_create_agents_app with name "my-workflow"; note the returned slug, which carries a random suffix
Create an orchestrator: nolag_create_orchestrator with name "dispatcher"
Create worker agents: nolag_create_agent with capabilities like "drafting", "research"
Dispatch tasks: nolag_dispatch_task to send work to connected agents
Monitor: nolag_list_agent_events to see what agents are doing
Check state: nolag_get_blackboard_state to see shared agent state

Each agent connects using the @nolag/agents SDK with its access token (returned once by the create tools above). The MCP service manages infrastructure; agents use the SDK for real-time coordination.