# Narla MCP connector

Work with your [Narla](https://narla.digital) AI agents from the assistant you already have open: ChatGPT, Claude or Cursor.

Narla installs AI agents inside a company: **Narla Marketing** (edits photos and video, writes and publishes posts, keeps the website and online shop up to date), **Narla Ops** (company systems and documents) and **Narla Voice** (answers customers by phone and WhatsApp). The team directs them in plain language. This connector, built on the open [Model Context Protocol](https://modelcontextprotocol.io), lets the team do that from any MCP-capable assistant.

## What it does

| Tool | Scope | What it does |
| --- | --- | --- |
| `list_agents` | read | The agents installed for the company and what each one does |
| `list_tasks` | read | Recent tasks and their status, newest first |
| `get_task` | read | One task: its instructions, its status and the agent's report (what it did and what it changed) |
| `read_business_memory` | read | The company's single source of truth: brand kit, services, prices, hours |
| `create_task` | write | Gives an agent a task in plain language. Saved as **Draft**: nothing runs yet |
| `cancel_task` | write | Voids a Draft task |
| `approve_task` | approve | Approves a Draft task so the agent starts it. Requires `confirm: true` |

**Nothing runs without a person's approval.** Every task starts as a Draft, and every finished task keeps a report. Narla Voice takes no instructions from staff; changes to it go through Narla Ops.

Tasks live in a Notion database (the queue the agents read). The connector only touches pages inside that one queue.

## Quick start

```bash
npm install
npm run build
NARLA_DEMO=1 NARLA_TOKENS="$(openssl rand -hex 32):read,write" npm start   # in-memory demo, no Notion
```

With Notion, copy `.env.example`, fill in a Notion integration token that has access **only** to the task queue (and, optionally, the business memory page), and start the server.

## Connect your assistant

### Cursor (local, no server needed)

Clone this repository, run `npm install && npm run build`, then add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "narla": {
      "command": "node",
      "args": ["/path/to/narla-mcp/dist/stdio.js"],
      "env": {
        "NOTION_TOKEN": "secret_xxx",
        "NARLA_QUEUE_DATA_SOURCE_ID": "your-data-source-id",
        "NARLA_TASK_PREFIX": "NARLA-TASK",
        "NARLA_SCOPES": "read,write"
      }
    }
  }
}
```

Cursor can also use the remote server: `"url": "https://your-host/mcp"` with header `Authorization: Bearer <token>`.

### ChatGPT and Claude (remote)

Deploy the HTTP server (any Node 20+ host). In the assistant's custom connector settings, add:

```
https://your-host/mcp/<your-token>
```

The token in the path is for apps whose connector settings take only a URL. Treat that URL as a password. Clients that support headers should use `Authorization: Bearer <token>` with `https://your-host/mcp` instead.

### Claude Desktop (local)

Same as Cursor, in `claude_desktop_config.json`.

## Configuration

| Variable | Required | Meaning |
| --- | --- | --- |
| `NOTION_TOKEN` | yes, unless `NARLA_DEMO=1` | Notion integration token |
| `NARLA_QUEUE_DATA_SOURCE_ID` | yes | Data source id of the task queue |
| `NARLA_TASK_PREFIX` | no | Task numbering prefix, e.g. `NARLA-TASK` gives `NARLA-TASK-12: ...` |
| `NARLA_MEMORY_PAGE_ID` | no | Notion page with the business memory |
| `NARLA_DEFAULT_MODEL` | no | Value for the queue's `Model` select on new tasks |
| `NARLA_TOKENS` | HTTP only | `token:scopes` pairs separated by `;`. Tokens must be 32+ characters |
| `NARLA_SCOPES` | stdio only | Scopes for local mode. Default `read,write` |
| `HOST`, `PORT`, `ALLOWED_HOSTS` | HTTP only | Bind address and allowed `Host` headers |

The queue is expected to have these properties: `Title` (title), `Status` (select with Draft, Approved, Running, Done, Failed, Voided), `Tier` (select: Low, Medium, High), `Result` (text, written by the agent), and optionally `Model` (select).

## Security

- Give each person their own token, with the smallest scope they need. Only the owner should have `approve`.
- Tokens are held in memory only as SHA-256 hashes and compared in constant time.
- The Notion integration should be shared with the queue and the memory page only. The connector refuses any page outside the configured queue.
- The HTTP server is stateless and keeps no conversation data.
- OAuth is on the roadmap; until then, rotate a token by changing `NARLA_TOKENS` and restarting.

Found a security issue? Write to contact@narla.digital rather than opening a public issue.

## Development

```bash
npm test        # vitest: tools, scopes, HTTP auth, Notion store
npm run dev     # HTTP server with tsx
```

## License

Apache License 2.0. Copyright 2026 NARLA S.R.L.