Paca MCP Server

Model Context Protocol (MCP) server for Paca — an open-source, AI-native project management platform.

Connect your AI assistant (Claude, Cursor, VS Code Copilot, etc.) to your Paca workspace and manage projects, tasks, sprints, and documents using natural language.

Getting Started

Prerequisites

• Node.js 18+
• A running Paca instance (local or deployed)
• A Paca API key (generate one in your Paca user settings)

Setup

No installation or build step required. Configure your AI agent client to use the MCP server directly via npx.

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | PACA_API_KEY | ✅ | — | API key for authentication (see below) | | PACA_API_URL | ❌ | http://localhost:8080 | URL of your Paca API instance | | PACA_AGENT_ID | ❌ | — | Agent UUID (required when using global agent API key) | | PACA_PROJECT_ID | ❌* | — | Project UUID for single-project mode (required when PACA_AGENT_ID is set) |

Claude Desktop

Add the following to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "paca": {
      "command": "npx",
      "args": ["-y", "@paca-ai/paca-mcp"],
      "env": {
        "PACA_API_KEY": "your-api-key-here",
        "PACA_API_URL": "http://localhost:8080"
      }
    }
  }
}

Restart Claude Desktop after saving. Claude will automatically have access to all Paca tools.

VS Code (GitHub Copilot)

Add to your VS Code settings.json or .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "paca": {
        "command": "npx",
        "args": ["-y", "@paca-ai/paca-mcp"],
        "env": {
          "PACA_API_KEY": "your-api-key-here",
          "PACA_API_URL": "http://localhost:8080"
        }
      }
    }
  }
}

Other MCP-Compatible Clients

Any MCP-compatible client can use the server with:

{
  "name": "paca",
  "command": "npx",
  "args": ["-y", "@paca-ai/paca-mcp"],
  "env": {
    "PACA_API_KEY": "your-api-key-here",
    "PACA_API_URL": "http://localhost:8080"
  }
}

For a full setup walkthrough, see the MCP Server Setup Guide.

Features

• API Key Authentication: Secure access using Paca API keys
• Agent-Specific Permissions: MCP tools are filtered based on agent's project permissions at startup
• Comprehensive Project Management: Full project lifecycle with member and role management
• Advanced Task Management: Tasks with types, statuses, custom fields, and attachments
• Sprint Management: Complete sprint lifecycle management
• Document Management: Documents with folder hierarchy, version history, and file support
• View Management: Multiple view types (sprint, backlog, timeline) with task positioning
• GitHub Integration: Repository linking, PR management, and branch creation
• Collaboration Tools: Comments and activities for team collaboration
• BlockNote Integration: Automatic conversion between BlockNote JSON and Markdown
• Plugin MCP Tools: Plugins can contribute additional MCP tools, loaded automatically at startup

Agent & User Permissions

The MCP server automatically filters available tools based on permissions, whether you're using it as an agent or as a regular user.

Agent Mode vs. User Mode

| Mode | Trigger | API Key Source | Permission Source | Scope | |---|---|---|---|---| | Agent Single-Project | PACA_AGENT_ID + PACA_PROJECT_ID | Global AGENT_API_KEY from server config | Agent's permissions in the specified project | Single project only | | User Single-Project | PACA_PROJECT_ID only (no PACA_AGENT_ID) | User's personal API key | User's global + project permissions | Single project | | User Global | No PACA_PROJECT_ID | User's personal API key | User's global permissions only | All projects (no project-scoped tools) |

Note: AI agents operate in single-project mode. The global AGENT_API_KEY is configured on the Paca server via the AGENT_API_KEY environment variable.

Agent Mode (Single-Project)

When both PACA_AGENT_ID and PACA_PROJECT_ID are set:

1. Authentication: Uses the global AGENT_API_KEY configured on the Paca server
2. Impersonation: X-Agent-ID header specifies which agent to act as
3. Permission Fetch: Only fetches permissions for the specified project
4. Tool Filtering: Shows only tools the agent has permission to use in that project
5. Project Validation: Enforces that all tool calls use the configured project ID
6. Performance: Optimized for single-project operations (single API call)

How to Get the Agent API Key:

The AGENT_API_KEY is configured on the Paca server, not per-agent. Check your server's environment:

# On the Paca server
echo $AGENT_API_KEY  # This is the global agent key to use

Configuration:

{
  "mcpServers": {
    "paca": {
      "command": "npx",
      "args": ["-y", "@paca-ai/paca-mcp"],
      "env": {
        "PACA_API_KEY": "server-agent-key-from-env",
        "PACA_API_URL": "http://localhost:8080",
        "PACA_AGENT_ID": "your-agent-uuid-here",
        "PACA_PROJECT_ID": "your-project-uuid-here"
      }
    }
  }
}

User configuration (optional single-project mode):

{
  "mcpServers": {
    "paca": {
      "command": "npx",
      "args": ["-y", "@paca-ai/paca-mcp"],
      "env": {
        "PACA_API_KEY": "your-api-key-here",
        "PACA_API_URL": "http://localhost:8080",
        "PACA_PROJECT_ID": "your-project-uuid-here"
      }
    }
  }
}

User Mode (No Agent ID)

When PACA_AGENT_ID is not set:

1. Authentication: Uses user's personal API key (from Settings → API Keys)
2. No Impersonation: Acts as the authenticated user directly
3. Global Permissions: Fetches global permissions via GET /api/v1/users/me/global-permissions
4. Tool Filtering: Shows only globally permitted tools (no project-scoped tools)
5. Best Practice: Set PACA_PROJECT_ID to filter tools at the MCP level and reduce API errors

Configuration:

{
  "mcpServers": {
    "paca": {
      "command": "npx",
      "args": ["-y", "@paca-ai/paca-mcp"],
      "env": {
        "PACA_API_KEY": "your-personal-api-key-here",
        "PACA_API_URL": "http://localhost:8080"
      }
    }
  }
}

To add project scope:

{
  "mcpServers": {
    "paca": {
      "command": "npx",
      "args": ["-y", "@paca-ai/paca-mcp"],
      "env": {
        "PACA_API_KEY": "your-personal-api-key-here",
        "PACA_API_URL": "http://localhost:8080",
        "PACA_PROJECT_ID": "your-project-uuid-here"
      }
    }
  }
}

Note: Without PACA_PROJECT_ID, project-scoped tools (like list_tasks, create_task) will not be available.

Supported Permissions

| Permission | Tools Requiring It | |---|---| | projects.read | list_projects, get_project | | projects.write | update_project, delete_project | | projects.create | create_project | | tasks.read | list_tasks, get_task, get_task_by_number, list_task_types, list_task_statuses | | tasks.write | create_task, update_task, delete_task, create_task_type, update_task_type, delete_task_type, set_default_task_type, create_task_status, update_task_status, delete_task_status, set_default_task_status | | sprints.read | list_sprints, get_sprint | | sprints.write | create_sprint, update_sprint, delete_sprint, complete_sprint | | docs.read | list_documents, get_document, list_doc_folders, list_doc_snapshots, get_doc_snapshot | | docs.write | create_document, update_document, delete_document, create_doc_folder, update_doc_folder, delete_doc_folder | | project.members.read | list_project_members, get_my_project_permissions | | project.members.write | add_project_member, update_project_member_role, remove_project_member | | project.roles.read | list_project_roles | | project.roles.write | create_project_role, update_project_role, delete_project_role |

Configuring Permissions

For Agents:

1. Add Agent as Project Member: Add the agent to the desired projects with appropriate roles
2. Configure Role Permissions: Ensure the assigned roles have the necessary permissions
3. Restart MCP Server: Restart the MCP server to refresh the permission cache

Important: When using agent mode:

• PACA_API_KEY must be a user's API key (not the agent's API key)
• PACA_AGENT_ID is the agent to impersonate
• The user who owns the API key must have permission to use/impersonate the agent

For Users:

1. Assign Global Roles: Grant users global permissions through their global roles
2. Add to Projects: Add users to projects with appropriate project roles
3. Configure Project Roles: Ensure project roles have the necessary permissions
4. Restart MCP Server: Restart the MCP server to refresh the permission cache

Example Configuration

{
  "mcpServers": {
    "paca": {
      "command": "npx",
      "args": ["-y", "@paca-ai/paca-mcp"],
      "env": {
        "PACA_API_KEY": "your-api-key-here",
        "PACA_API_URL": "http://localhost:8080",
        "PACA_AGENT_ID": "your-agent-uuid-here"
      }
    }
  }
}

Note: The MCP server automatically filters tools based on your permissions:

• With PACA_AGENT_ID: Filters tools based on the agent's project permissions
• Without PACA_AGENT_ID: Filters tools based on your personal user permissions (including global permissions)

If permission fetching fails, all tools will be shown to maintain backward compatibility.

Available Tools

The MCP server provides 81 tools across 16 categories for comprehensive project management.

📁 Project Management (5 tools)

• list_projects - List all accessible projects
• get_project - Get details of a specific project
• create_project - Create a new project
• update_project - Update an existing project
• delete_project - Delete a project

✅ Task Management (6 tools)

• list_tasks - List all tasks in a project
• get_task - Get details of a specific task
• get_task_by_number - Get a task by its number
• create_task - Create a new task
• update_task - Update an existing task
• delete_task - Delete a task

🏃 Sprint Management (6 tools)

• list_sprints - List all sprints in a project
• get_sprint - Get details of a specific sprint
• create_sprint - Create a new sprint
• update_sprint - Update an existing sprint
• delete_sprint - Delete a sprint
• complete_sprint - Mark a sprint as completed

📄 Document Management (5 tools)

• list_documents - List all documents in a project
• get_document - Get details of a specific document
• create_document - Create a new document
• update_document - Update an existing document
• delete_document - Delete a document

👥 Project Members (5 tools)

• list_project_members - List all members of a project
• add_project_member - Add a member to a project
• get_my_project_permissions - Get the current user's permissions
• update_project_member_role - Update a member's role
• remove_project_member - Remove a member from a project

🎭 Project Roles (4 tools)

• list_project_roles - List all roles in a project
• create_project_role - Create a new project role
• update_project_role - Update an existing project role
• delete_project_role - Delete a project role

🏷️ Task Types (5 tools)

• list_task_types - List all task types in a project
• create_task_type - Create a new task type
• update_task_type - Update an existing task type
• delete_task_type - Delete a task type
• set_default_task_type - Set a task type as default

📊 Task Statuses (4 tools)

• list_task_statuses - List all task statuses in a project
• create_task_status - Create a new task status
• update_task_status - Update an existing task status
• delete_task_status - Delete a task status

🎯 Views (9 tools)

• list_views - List all views in a project
• create_view - Create a new view (sprint/backlog/timeline)
• reorder_views - Reorder views in a project
• get_view - Get details of a specific view
• update_view - Update an existing view
• delete_view - Delete a view
• list_task_positions - List task positions in a view
• bulk_move_tasks - Bulk move tasks in a view
• move_task - Move a task within a view

🔧 Custom Fields (5 tools)

• list_custom_fields - List all custom field definitions
• create_custom_field - Create a new custom field definition
• get_custom_field - Get details of a custom field
• update_custom_field - Update a custom field definition
• delete_custom_field - Delete a custom field definition

📎 Attachments (3 tools)

• list_task_attachments - List all attachments for a task
• get_attachment_download_url - Get a download URL for an attachment
• delete_task_attachment - Delete an attachment

📁 Document Folders (4 tools)

• list_doc_folders - List all folders in a project
• create_doc_folder - Create a new document folder
• update_doc_folder - Update a document folder
• delete_doc_folder - Delete a document folder

📸 Document Snapshots (2 tools)

• list_doc_snapshots - List all snapshots of a document
• get_doc_snapshot - Get a specific document snapshot

🔗 GitHub Integration (7 tools)

• get_github_integration - Get GitHub integration status
• set_github_token - Set GitHub token for a project
• delete_github_token - Delete GitHub token
• list_github_repositories - List available GitHub repositories
• list_linked_github_repos - List linked repositories
• link_github_repository - Link a GitHub repository
• unlink_github_repository - Unlink a GitHub repository

💬 Task Activities (4 tools)

• list_task_activities - List all activities for a task
• add_task_comment - Add a comment to a task
• update_task_comment - Update a task comment
• delete_task_comment - Delete a task comment

🔀 Task GitHub (5 tools)

• list_task_prs - List pull requests linked to a task
• link_pr_to_task - Link a pull request to a task
• unlink_pr_from_task - Unlink a pull request
• create_branch_for_task - Create a branch for a task
• list_task_branches - List branches for a task

For a complete list of all tools with detailed descriptions, see ALL_TOOLS.md.

🔌 Plugin Tools

Installed Paca plugins can contribute additional MCP tools. When the server starts it fetches GET /api/v1/plugins, and for each enabled plugin that declares an mcp.remoteEntryUrl in its manifest, dynamically loads the plugin's tool module and merges its tools into the list above.

Plugin tools appear alongside core tools — there is no distinction from the AI client's perspective.

To add MCP tools to your own plugin, see the MCP Plugin System docs and the @paca-ai/plugin-sdk-mcp SDK.

Markdown/BlockNote Conversion

The MCP server automatically handles conversion between Markdown and BlockNote JSON format:

• Reading: Fetches content as BlockNote JSON and converts to Markdown for readability
• Writing: Accepts Markdown input and converts to BlockNote JSON for storage

This allows AI assistants to work with familiar Markdown format while the API stores content in BlockNote's rich text format.

API Key Authentication

All tools authenticate via the X-API-Key header. Generate an API key in your Paca user settings and set it as PACA_API_KEY in your MCP client configuration.

Examples

Create a Task with Markdown Description

Tool: create_task
Arguments:
- projectId: "project-uuid"
- title: "Implement user authentication"
- description: "# Implementation Plan\n\n## Steps\n1. Create auth service\n2. Add login endpoint\n3. Implement JWT tokens"
- statusId: "status-uuid"
- importance: 5
- tags: ["auth", "backend"]

Update Document Content

Tool: update_document
Arguments:
- projectId: "project-uuid"
- docId: "doc-uuid"
- content: "# System Design\n\n## Architecture\nThis document describes the..."

Notes

• The server requires a running Paca API instance
• API keys can be created through the Paca web interface under user settings
• All descriptions and document contents are automatically converted between Markdown and BlockNote format
• Date fields should be provided in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)

Contributing

Interested in contributing to the MCP server? Clone the repository and follow the steps below:

git clone https://github.com/paca-ai/paca.git
cd paca/apps/mcp
npm install
npm run build

For development with auto-rebuild:

npm run watch

To test with the MCP Inspector:

npm run inspector

For detailed information about the codebase structure, how to add new tools, and code style guidelines, see DEVELOPMENT.md.

License

Apache License 2.0