---
title: MCP Setup for AI Agents
description: How to connect Claude Desktop, Cursor, or any MCP client to NoLag for AI agent infrastructure management.
---

# MCP Setup for AI Agents

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-level API key. Create one in the [Portal](https://portal.nolag.app) under Settings → API Keys.

## Quick Start

1. Create a project in the [NoLag Portal](https://portal.nolag.app)
2. Generate a project-level API key (format: `nl_live_yourKeyId.yourSecret`)
3. Add the NoLag MCP server to your AI client's configuration (see below)
4. 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):

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

Replace `nl_live_yourKeyId.yourSecret` with your actual API key.

**Note:** This uses `mcp-remote` to bridge the SSE transport to stdio. It will be installed automatically via `npx` on first run.

## Cursor

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

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

## Custom MCP Clients (HTTP)

NoLag supports both **SSE transport** (`GET /mcp/sse`) and **plain HTTP** (`POST /mcp`) for MCP. Use SSE for streaming clients; use HTTP for simple request/response integrations.

```text
# Initialize session
curl -X POST https://api.nolag.app/mcp \
  -H "Authorization: Bearer nl_live_yourKeyId.yourSecret" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {}
  }'

# List available tools
curl -X POST https://api.nolag.app/mcp \
  -H "Authorization: Bearer nl_live_yourKeyId.yourSecret" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/list",
    "params": {}
  }'

# Create an agent actor
curl -X POST https://api.nolag.app/mcp \
  -H "Authorization: Bearer nl_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 | Use Case |
| --- | --- | --- |
| SSE via mcp-remote (recommended) | `GET /mcp/sse` | Claude Desktop, Claude Code, Cursor, and other MCP clients |
| HTTP | `POST /mcp` | Simple integrations, scripts, testing |

## Available Tools

The NoLag MCP server exposes **31 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 |

### 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 persistent sessions 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_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

All MCP requests require a **project-level API key**. Organization-level and system keys are not supported for MCP. There are two ways to authenticate:

### Option 1: Authorization Header (recommended)

```text
Authorization: Bearer nl_live_yourKeyId.yourSecret
```

### Option 2: Query Parameter

For MCP clients that use `mcp-remote` or don't support custom headers, pass the token as a query parameter. This is the recommended approach for Claude Desktop, Claude Code, and Cursor:

```text
https://api.nolag.app/mcp/sse?token=nl_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's a typical workflow using MCP to set up a multi-agent system:

1. **Create an agents app:** `nolag_create_agents_app` with name "my-workflow"
2. **Create an orchestrator:** `nolag_create_orchestrator` with name "dispatcher"
3. **Create worker agents:** `nolag_create_agent` with capabilities like "drafting", "research"
4. **Dispatch tasks:** `nolag_dispatch_task` to send work to connected agents
5. **Monitor:** `nolag_list_agent_events` to see what agents are doing
6. **Check state:** `nolag_get_blackboard_state` to see shared agent state

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