MCP (Model Context Protocol)

Projectyl supports the Model Context Protocol (MCP), which lets AI tools read and write your project data directly. Instead of copying tasks into a chat prompt or summarising a doc for your AI assistant, you connect Projectyl once and the AI has what it needs.

This is useful for teams already working with Claude, Cursor, or other MCP-compatible tools. It's not required, and it won't change anything if you don't use it — but if you do use AI tools regularly, this is the part that makes them actually useful in your workflow.

Under the hood, Projectyl uses OAuth 2.1 with PKCE to authorize these clients, so each app gets its own revocable grant bound to a single workspace.

Supported clients

Projectyl accepts connections from these MCP clients (allowlisted by name):

• Claude Desktop
• Claude Code
• Cursor
• Claude.ai connectors
• MCP Inspector (for development and testing)

Other MCP clients are rejected at the registration step. If you want a new client added, email support@projectyl.app.

Connecting a client

Claude Desktop

1. In Claude Desktop's settings, add a new MCP server.
2. Set the URL to https://<your-projectyl-domain>/api/mcp.
3. Claude Desktop will open your browser to authorize the connection.
4. Sign in to Projectyl if prompted.
5. On the consent screen, choose the workspace and click Allow.
6. Claude Desktop is now connected. Tools appear in the conversation UI.

Claude Code

claude mcp add --transport http projectyl https://<your-projectyl-domain>/api/mcp

Use --scope project to keep the connection per-repository, or --scope user to make it available across all projects under your user.

Follow the browser prompts (same consent screen as Claude Desktop).

Cursor

In Cursor's settings, add a remote MCP server with URL https://<your-projectyl-domain>/api/mcp. The consent flow is the same.

What a grant covers

Each authorization grant is scoped to:

• One workspace. Chosen on the consent screen. To connect the same client to a different workspace, run the OAuth flow again and pick the other workspace — this creates a second independent grant.
• Read or read+write. The client requests its needed scopes at authorization time; you see them on the consent screen.
• The specific device that authorized. The consent flow captures the browser user agent so you can identify which grant is which in Settings.

Access tokens expire after 1 hour; clients silently refresh them using a long-lived refresh token (30 days). No user action is needed during the refresh — it happens in the background.

Available tools

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

Workspace

• whoami — Check the current user and workspace 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

Managing connections

Visit Settings → Connected Apps to see all active grants in the current workspace. For each grant you can:

• See the client, scopes, connected date, and last-used time.
• Revoke the grant. The client will be prompted to re-authorize on its next request.

Security notes

• Tokens are stored hashed (SHA-256) in our database; we never store plaintext.
• Revocations take effect immediately — the next request from the revoked client returns 401.
• Only the redirect URIs specified in each client's allowlist entry are accepted. This prevents impersonation.

Discovery endpoints

For tooling and MCP clients that discover auth via standard metadata:

• /.well-known/oauth-protected-resource (RFC 9728)
• /.well-known/oauth-authorization-server (RFC 8414)

Both are public.

Troubleshooting

"Unknown client" error on consent screen. Your MCP client isn't in the allowlist. Email support@projectyl.app to request support.

"Invalid redirect URL" error. Your client's redirect URI doesn't match the registered patterns. This can happen after a client update changes the redirect scheme. Email support@projectyl.app; we'll update the allowlist.

Tool call returns 401 after a while. Your token was revoked, or you switched workspaces in Projectyl. Re-run the client's connection flow.

Previously worked with a Personal Access Token, now 401. PATs have been replaced by OAuth. Reconnect your MCP client via the new flow above.