MCP Server

Nenjo includes a built-in Model Context Protocol server that exposes platform resources as tools. Any MCP-compatible client can connect and interact with tickets, projects, agents, pipelines, and more.

Connection Details

Authentication

The MCP endpoint requires an API key. Pass it via either header:

# Authorization header
curl -X POST -H "Authorization: Bearer nen_<key>" ...

# X-API-Key header
curl -X POST -H "X-API-Key: nen_<key>" ...

The key's scopes determine which tools are visible and callable. See API Keys for creating keys.

Protocol Flow

1. Initialize

curl -X POST \
  -H "Authorization: Bearer nen_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }' \
  https://your-instance/mcp

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "nenjo",
      "version": "0.1.0"
    }
  }
}

2. Send Initialized Notification

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized",
  "params": {}
}

This is a notification (no id field). The server responds with 204 No Content.

3. List Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Returns all tools the key's scopes allow. Each tool includes its name, description, input schema, and required scope.

4. Call a Tool

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "tickets_list",
    "arguments": {
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "open",
      "limit": 10
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\": \"...\", \"title\": \"...\", ...}]"
      }
    ]
  }
}

Tool results are returned as text content containing pretty-printed JSON.

Supported Methods

Tool Reference

Tools are organized by resource group. Each tool has a required scope.

Tickets

tickets_list parameters:

tickets_create required parameters: project_id, title

tickets_create optional parameters: description, status (open, ready, backlog), priority, type, tags (string array), complexity (1-5), acceptance_criteria

Projects

projects_create required parameters: name

projects_create optional parameters: description

projects_update required parameters: id

projects_update optional parameters: name, description, settings (object)

Documents

documents_list required parameters: project_id

documents_delete required parameters: project_id, document_id

Agents and Roles

agents_create required parameters: name, model

agents_create optional parameters: description, model_provider (openai, anthropic, google; default openai), temperature (0-2, default 0.7), tags (string array)

Pipelines

pipelines_create required parameters: name, trigger

pipelines_create optional parameters: description, is_active (default true), max_retries (default 3), metadata (object)

Trigger values: ticket.ready, chat.message, cron

pipeline_steps_create required parameters: pipeline_id, name, step_type

Step types: agent, gate, terminal, council, lambda

pipeline_steps_create optional parameters: agent_id, council_id, role_id, lambda_id, config (object), order_index (integer), position_x, position_y

pipeline_edges_create required parameters: pipeline_id, source_step_id, target_step_id

Edge conditions: always (default), on_pass, on_fail, on_review_pass, on_review_fail

Executions

executions_list parameters: project_id (uuid), status (string), limit (default 50, max 200), offset (default 0)

Councils

councils_create required parameters: name, leader_role_assignment_id, members (array)

councils_create optional parameters: description, delegation_strategy (round_robin, priority, random; default round_robin), config (object)

Member objects: role_assignment_id (required), priority (integer, default 0)

Chat

chat_sessions_list required parameters: project_id, role_id

chat_sessions_list optional parameters: include_archived (boolean, default false)

chat_messages_list required parameters: project_id, role_id, session_id

chat_messages_list optional parameters: limit (default 50, max 200), before (ISO-8601 timestamp)

Graph

Both tools require: project_id

Error Handling

If a tool call fails due to insufficient scopes:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32001,
    "message": "Scope 'tickets:write' required for tool 'tickets_create'"
  }
}

If a tool is not found:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32601,
    "message": "Tool not found: nonexistent_tool"
  }
}