MCP Integration

Connect AI assistants to your Projectyl workspace using the Model Context Protocol (MCP). Once connected, your AI assistant can read and create tasks, documents, targets, and more — directly from your editor or terminal.

Creating an API Token

1. Go to Settings → API Tokens tab
2. Click Create Token
3. Enter a name (e.g., "Claude Code")
4. Select the scopes you need (all are selected by default)
5. Click Create

After creation, a ready-to-use MCP configuration snippet is displayed. Copy it into your AI assistant's config file.

Connecting Your AI Assistant

The configuration snippet shown after token creation looks like this:

{
  "mcpServers": {
    "projectyl": {
      "url": "https://projectyl.app/api/mcp",
      "headers": {
        "Authorization": "Bearer pyl_your-token-here"
      }
    }
  }
}

Where to paste this depends on your AI assistant:

After adding the config, restart your assistant or reload the MCP server list.

Available Scopes

Scopes control what your AI assistant can do. Choose only what you need.

Available Tools

Once connected, your AI assistant has access to these tools:

Workspace

• whoami — Check the current user and token info
• get_workspace_info — View workspace details

Projects

• list_projects — List all accessible projects
• get_project — View project details
• list_project_members — View project members and roles

Tasks

• list_tasks — List tasks with filtering and pagination
• get_task — View a task with all relations
• create_task — Create a new task
• update_task — Update a task

Documents

• list_documents — List documents with search and pagination
• get_document — View a document including its full content
• create_document — Create a new document
• update_document — Update a document

Targets

• list_targets — List targets with optional filters
• get_target — View a target with full details
• create_target — Create a new target
• update_target — Update a target

Dependencies

• list_task_dependencies — View a task's predecessors and successors
• create_task_dependency — Create a dependency between two tasks
• delete_task_dependency — Remove a dependency

Other

• list_comments — View comments on a task or document
• list_states — View workflow states for a project
• list_labels — View labels for a project
• get_help — Get usage guidance for the MCP tools

Rate Limits

To ensure fair usage, MCP requests are rate-limited:

If you hit a rate limit, you'll receive an HTTP 429 response with a Retry-After header indicating when to retry.

Managing Tokens

• Each user can have one token per workspace
• Tokens can be revoked at any time from Settings → API Tokens
• Revoking a token immediately disconnects any MCP clients using it
• To rotate a token, revoke the existing one and create a new one