403 Forbidden in MCP: Permissions and Access Control Fixes

Getting 403 Forbidden errors? Your API key is valid, but you don't have permission to perform the requested action. This guide explains account-level access issues, scope/permission mismatches, and how to validate your key is tied to the right workspace—with safe troubleshooting steps that avoid exposing secrets.

What 403 Forbidden Means

A 403 error indicates that authentication succeeded (your API key is valid), but authorization failed (you don't have permission for the requested action). This is different from 401 Unauthorized, which means authentication failed.

Key Difference: 401 vs 403

• 401 Unauthorized: Authentication failed (invalid API key or missing header)
• 403 Forbidden: Authentication succeeded, but permission denied (key valid but lacks required access)

Common Causes of 403 Errors

1. Account-Level Access Issues

Your account may not have access to the workspace or resource:

• API key belongs to a different workspace
• Account was removed from the workspace
• Workspace access was revoked
• Account permissions changed

2. Scope/Permission Mismatches

The API key may not have the required permissions:

• Key has read-only access but you're trying to write
• Key lacks permission for specific operations (create, update, delete)
• Key is restricted to certain projects or boards

3. Resource Access Restrictions

You may not have access to the specific resource:

• Trying to access a project you're not a member of
• Attempting to modify a task you don't own
• Accessing a board you don't have permission for

Step 1: Validate Workspace Access

First, confirm your API key is tied to the correct workspace:

Safe Validation Steps (No Secret Exposure)

1. Log in to Corcava in your browser
2. Check which workspace you're currently viewing (top-left workspace selector)
3. Go to Settings → Integrations → Public API
4. Find your API key in the list
5. Verify the key name matches what you're using in MCP config
6. Check if the key shows the correct workspace name

Security Note

Never paste your API key into chat, logs, or error messages. These validation steps use the Corcava web interface, not the API key itself.

Workspace Mismatch Issues

Wrong Workspace

• Symptom: Key exists but belongs to a different workspace than expected
• Fix: Either switch to the correct workspace in Corcava, or create a new API key in the workspace you need

Account Removed from Workspace

• Symptom: Key was valid but account was removed from workspace
• Fix: Request workspace access again, or use a key from a workspace you have access to

Step 2: Check Permission Scope

Verify your API key has the required permissions for the operation you're trying to perform:

Read vs Write Operations

Read operations (usually allowed):

• list_tasks - List tasks
• get_task - Get task details
• list_projects - List projects
• list_boards - List boards
• list_task_comments - List comments

Write operations (may require permissions):

• create_task - Create tasks
• update_task - Update tasks
• delete_task - Delete tasks
• add_task_comment - Add comments
• start_time_tracking - Start timers

Test Read Operations First

If you're getting 403 errors, test with read-only operations to verify basic access:

Safe Test Commands

Test read access with these prompts (safe, no data changes):

• "List my projects" (tests list_projects)
• "Show me my tasks" (tests list_tasks)
• "What boards are available?" (tests list_boards)

If read operations work but write operations fail, you have a permission scope issue.

Step 3: Verify Resource Access

Even with a valid API key, you may not have access to specific resources:

Project Access

Check project membership:

1. In Corcava web interface, verify you're a member of the project
2. Check project settings to confirm your role
3. Verify the project ID you're using in MCP calls matches an accessible project

Task Access

Check task ownership/permissions:

• Some tasks may be restricted to specific users
• Verify the task ID exists and is accessible
• Check if you're trying to modify a task you don't own

Board Access

Check board permissions:

• Verify you have access to the board
• Check board settings for access restrictions
• Confirm the board ID is correct

Step 4: Safe Troubleshooting Process

Follow these steps to diagnose 403 errors without exposing secrets:

Safe Diagnostic Workflow

1. Test read operations: Try listing projects or tasks (read-only)
2. Check workspace: Verify you're in the correct workspace in Corcava web interface
3. Verify key workspace: Confirm API key belongs to the same workspace
4. Test write operations: Try a simple write (e.g., add comment) to see if it's a write permission issue
5. Check resource access: Verify you have access to the specific project/task/board
6. Review error message: Check the 403 error payload for specific permission details

Never Expose Secrets

When troubleshooting or asking for help:

• Never paste your API key
• Never share full error responses that might contain sensitive data
• Use placeholder values (e.g., "YOUR_API_KEY") when describing issues
• Describe the error type and operation, not the actual key or data

Step 5: Interpret Error Messages

403 error responses often include details about what permission is missing:

Common 403 Error Patterns

"Access denied to workspace"

• Meaning: API key belongs to different workspace
• Fix: Verify workspace in Corcava, create key in correct workspace

"Insufficient permissions"

• Meaning: Key lacks required permission for the operation
• Fix: Check if operation requires write access, verify key permissions

"Resource not accessible"

• Meaning: You don't have access to the specific resource (project/task/board)
• Fix: Verify resource exists and you're a member/have access

Step 6: Fix Permission Issues

Based on the diagnosis, apply the appropriate fix:

Fix: Wrong Workspace

1. Log into Corcava and switch to the correct workspace
2. Go to Settings → Integrations → Public API
3. Create a new API key in the correct workspace
4. Update your MCP config with the new key
5. Restart your MCP client
6. Test with a read operation first

Fix: Insufficient Permissions

If your key lacks required permissions:

1. Verify what permissions your key has (check in Corcava Settings)
2. If key is read-only but you need write access, create a new key with write permissions
3. Update MCP config with the new key
4. Test write operations

Fix: Resource Access

If you don't have access to a specific resource:

1. In Corcava web interface, verify you're a member of the project
2. Check project/board settings for access restrictions
3. Request access from project admin if needed
4. Use a different project/board that you have access to

Quick Fix Checklist

Before Escalating

• ✅ Tested read operations (list_tasks, list_projects) - do they work?
• ✅ Verified workspace in Corcava web interface matches API key workspace
• ✅ Confirmed API key is active and not revoked
• ✅ Checked project/board membership in Corcava
• ✅ Verified resource IDs (project, task, board) are correct
• ✅ Tested with a different resource you know you have access to

Related Troubleshooting

• 401 Unauthorized - Fix authentication issues before checking permissions
• Tool Calls Fail - Debug input validation and argument errors
• Tools Not Listed - Fix issues when tools don't appear
• Troubleshooting Index - Browse all troubleshooting guides