MCP Setup

Connect Claude Code to your Celune workspace via the Model Context Protocol — in about 5 minutes.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude connect to external tools and services. Instead of Claude operating in isolation, MCP gives it live access to the data and actions your platform exposes.

Celune's MCP server gives Claude Code direct access to your workspace: tasks, projects, memory, and agent configuration. When you open Claude Code in your project, your Agent Lead is right there with you — aware of what's in flight, able to create tasks, and able to recall past context.

MCP connections run locally on your machine. Your Celune API key authenticates each request — no data is stored by the MCP server itself.

Prerequisites

Before you begin, make sure you have:

Claude Code installed — claude.ai/download
A Celune account with at least one workspace created
Node.js 18+ installed (required to run the MCP server via npx)

Step 1: Create an API Key

Your API key authenticates the MCP server with your Celune workspace.

Go to the Celune dashboard and open Settings → API Keys.
Click Create API Key.
Give it a name like Claude Code — Local so you can identify it later.
Copy the key immediately — it will not be shown again.

Store your API key somewhere safe. If you lose it, you can revoke the old one and create a new one from the same settings page.

You will also need your Workspace ID, which is visible on the Settings → General page.

Step 2: Configure MCP

Add the Celune MCP server to your MCP configuration. You have two options:

Option A: Project-level config (recommended)

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "celune": {
      "command": "npx",
      "args": ["-y", "@celune/mcp-server"],
      "env": {
        "CELUNE_API_KEY": "<your-api-key>",
        "CELUNE_WORKSPACE_ID": "<your-workspace-id>"
      }
    }
  }
}

Replace <your-api-key> and <your-workspace-id> with your actual values. Commit this file to your repo so teammates can use the same config — they will need their own API keys.

Option B: Global Claude Code settings

If you want Celune available in every project, add the same block to your Claude Code global MCP settings file (usually ~/.claude/settings.json under mcpServers).

Do not commit .mcp.json with real API keys to a public repository. Add CELUNE_API_KEY to your .env.local and reference it, or use Option B for personal keys.

Step 3: Verify the Connection

Restart Claude Code (or open a new session in your project directory).
In Claude Code, run:

/mcp

You should see celune listed as a connected server with a green status indicator.
You can also verify via the API directly:

curl https://api.celune.ai/api/user/level \
  -H "Authorization: Bearer <your-api-key>"

A successful response looks like:

{
  "level": "pro",
  "workspace": "your-workspace-id",
  "status": "active"
}

If the server connects successfully, your Agent Lead's tools will appear in Claude Code's tool list.

Available Tools

Once connected, Claude Code gains access to the following Celune tools:

| Tool | Category | What it does | | ------------------------- | -------- | --------------------------------------------- | | celune_create_task | Tasks | Create a new task in your workspace | | celune_list_tasks | Tasks | List tasks by status, assignee, or project | | celune_update_task | Tasks | Update task status, priority, or description | | celune_complete_task | Tasks | Mark a task as complete with an outcome | | celune_list_projects | Projects | View all projects and their current status | | celune_get_project | Projects | Get details for a specific project | | celune_remember | Memory | Store a memory for your Agent Lead | | celune_recall | Memory | Retrieve relevant memories by semantic search | | celune_get_agent_config | Agents | Read configuration for a specific agent |

The tools your Agent Lead can call are governed by your workspace role. Members and above can manage tasks. Only owners and admins can modify agent configuration.

Troubleshooting

"MCP server not found" or celune does not appear in `/mcp`

Make sure Node.js 18+ is installed: node --version
Confirm .mcp.json is in the root of the directory you opened in Claude Code
Try running the server manually to see raw errors:

CELUNE_API_KEY=<your-key> CELUNE_WORKSPACE_ID=<your-id> npx -y @celune/mcp-server

"Invalid API key" or 401 errors

Double-check you copied the full key — they are long and easy to truncate
Verify the key is still active in Settings → API Keys
Make sure you are using the key for the correct workspace

"Workspace not found" or 404 errors

Confirm the CELUNE_WORKSPACE_ID matches exactly what is shown in Settings → General
Workspace IDs are UUID format — they do not use your workspace handle/slug

Tools appear but calls fail silently

Check that your plan includes MCP access (Pro and above)
Review the MCP server logs — Claude Code surfaces these in the Output panel under MCP
Try revoking and recreating your API key

Next Steps

Getting Started — Full onboarding walkthrough if you have not set up your workspace yet
Concepts: Agents — Understand agent roles, permissions, and how task routing works
API Reference — Direct REST API access for custom integrations