403 Forbidden : corriger les erreurs de permission MCP

Resolve MCP 403 Forbidden errors caused by insufficient permissions, scope mismatches, or workspace access issues. Learn about API key scopes and permission requirements for each tool.

Understanding 403 Forbidden

A 403 Forbidden error means your request was authenticated (API key is valid) but you don't have permission to perform the requested operation. This is different from 401 Unauthorized.

403 vs 401

401 Unauthorized: API key is missing, invalid, or revoked (authentication failed)
403 Forbidden: API key is valid but lacks permission for the operation (authorization failed)

See 401 guide if you're getting authentication errors instead.

Common Causes

1. API Key Scope Mismatch

Your API key doesn't have the required scope for the operation:

Scope Examples

Read-only key: Can call list_tasks and get_task, but NOT create_task or update_task
No time tracking: Can manage tasks but NOT start_time_tracking or stop_time_tracking
Limited projects: Can only access tasks in specific projects

How to Check

Log in to Corcava web app
Go to Settings → API Keys
Find your API key and check its permissions/scopes
Verify it has the required scope for your operation

2. Workspace Access Issues

Trying to access resources in a workspace you don't have access to:

Common Scenarios

Using task ID from workspace A while API key is for workspace B
Trying to access archived or deleted workspace
API key created by different user with different workspace access

Solution

Ensure your API key and the resources you're accessing are from the same workspace. Check workspace ID in the Corcava app.

3. Project-Level Permissions

You have workspace access but not permission for specific projects:

Project Access Levels

Owner/Admin: Full access to all project tasks
Member: Can view and edit tasks assigned to them
Viewer: Can only view tasks, cannot edit
No access: Cannot see or interact with project

Fix

Ask your workspace admin to grant you access to the project, or use a different API key with appropriate permissions.

4. Resource-Specific Restrictions

Some operations have additional restrictions:

Common Restrictions

Delete operations: Often require admin/owner permissions
Time tracking: May require time tracking feature enabled
Closed tasks: Cannot edit tasks that are marked as done/archived
Locked projects: Cannot modify tasks in locked projects

Permission Requirements by Tool

Tool	Required Permission	Common Issues
list_tasks	Read access	Project visibility
get_task	Read access	Task in inaccessible project
create_task	Write access + project member	Read-only key or project viewer
update_task	Write access + task access	Can't edit others' tasks
delete_task	Admin/owner access	Members can't delete
start_time_tracking	Time tracking enabled	Feature not enabled

Diagnostic Steps

Systematic Troubleshooting

Verify API key scope: Check in Settings → API Keys for key permissions
Test read-only first: Try list_tasks - if this fails, it's a workspace access issue
Check project access: Verify you have access to the specific project
Test with different task: Try a task you created vs one created by someone else
Review error message: Look for clues about which permission is missing
Check feature flags: Ensure required features (time tracking, etc.) are enabled

Solutions

1. Upgrade API Key Scope

How to Fix

Log in to Corcava web app
Go to Settings → API Keys
Find your API key or create a new one
Enable required scopes (read, write, admin, time tracking)
Update your MCP config with the new key if needed

2. Request Project Access

For Team Members

Ask your workspace admin or project owner to:

Add you to the project with appropriate role
Change your role from Viewer to Member or Admin
Enable required features (time tracking) for your account

3. Use Least Privilege Workflows

Best Practice

Create separate API keys with different scopes for different workflows:

Read-only key: For status reports and planning workflows
Write key: For task creation and updates
Admin key: Only for delete operations and admin tasks

See Least Privilege guide for details.

Quick Fix Checklist

✅ API key is valid and not expired
✅ API key has required scope for the operation
✅ Working in correct workspace (check workspace ID)
✅ Have access to the specific project
✅ Required features are enabled (time tracking, etc.)
✅ Not trying to edit read-only resources
✅ Have appropriate role (admin for delete operations)