AI Assistant Integration (MCP)

Overview

This guide explains how to connect AI assistants like Claude Desktop, Cursor, Windsurf, and Continue to your Corcava workspace using Model Context Protocol (MCP). Once connected, your AI assistant can read tasks, create tasks, track time, and help you work more efficiently through natural conversation.

What you'll learn:

How to get your API key
Universal configuration format for all clients
Client-specific setup guides
How to verify your connection
What your AI can do with Corcava

For detailed, client-specific setup instructions, see our dedicated guides:

Claude Desktop Setup - macOS, Windows, Linux
Cursor Setup - IDE-focused with workflow examples
Windsurf Setup - Settings UI configuration
Continue Setup - SSE transport configuration

What is MCP?

MCP (Model Context Protocol) is an open standard that allows AI assistants to connect to external tools and data sources. With Corcava's MCP integration, your AI assistant gains direct access to your projects, tasks, and time tracking.

Getting Your API Key

Before configuring your AI assistant, you need an API key:

Go to Settings → Integrations
Find the Public API section
Click Add API Key
Copy the generated key immediately (it's only shown once)
Store it securely - you'll need it for configuration

Tip: Create separate API keys for different AI assistants so you can manage access independently.

Universal Configuration

All MCP clients need these two pieces of information to connect to Corcava:

Endpoint URL:

https://app.corcava.com/mcp

Authorization Header:

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with the API key you copied in the previous step.

Configuration Format

The exact JSON structure varies by client, but all clients need:

The Corcava endpoint URL: https://app.corcava.com/mcp
An Authorization header with your API key: Bearer YOUR_API_KEY

Example configuration structure (format varies by client):

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Note: Continue uses a slightly different format with SSE transport. See the Continue setup guide for details.

Client-Specific Setup

Each AI assistant has its own configuration file location and format. Follow the dedicated setup guide for your client:

Claude Desktop Setup - Step-by-step guide for macOS, Windows, and Linux
Cursor Setup - IDE-focused setup with workflow examples
Windsurf Setup - Settings UI configuration guide
Continue Setup - SSE transport configuration

Each guide includes:

Exact configuration file locations for your operating system
Complete JSON configuration snippets with placeholders
Platform-specific instructions
Troubleshooting tips

Verification Checklist

After configuring your AI assistant, use this checklist to verify everything is working:

✅ Step 1: Configuration File

Configuration file exists and is in the correct location
JSON syntax is valid (no trailing commas, proper quotes)
Endpoint URL is exactly: https://app.corcava.com/mcp
Authorization header uses format: Bearer YOUR_API_KEY (with space after "Bearer")
API key is copied correctly (no extra spaces or characters)

✅ Step 2: Restart Client

AI assistant has been fully restarted (not just reloaded)
All windows/instances of the client have been closed and reopened

✅ Step 3: Verify Tools Are Available

Test that your AI assistant can see Corcava tools by asking:

For Claude Desktop, Cursor, or Windsurf:

"What MCP tools are available from Corcava?"

For Continue:

"List available MCP tools"

Expected result: Your AI should list Corcava MCP tools like list_tasks, create_task, start_time_tracking, etc.

✅ Step 4: Test a Read Operation

Try a simple read operation:

"List my tasks from Corcava"

Expected result: Your AI should retrieve and display your tasks (or say you have no tasks).

✅ Step 5: Test Connection Status

Ask your AI:

"Can you connect to Corcava?"

Expected result: Your AI should confirm it can access Corcava tools.

Common Issues

If tools don't appear:

Verify the configuration file location is correct for your OS
Check JSON syntax is valid (use a JSON validator)
Ensure you restarted the client completely
Verify the API key is active in Settings → Integrations

If you get "Authorization failed":

Check the Authorization header format: Bearer YOUR_API_KEY (with space)
Verify the API key is correct and active
Ensure no extra spaces or characters in the key

If connection fails:

Verify your internet connection
Check if https://app.corcava.com is accessible in your browser
Try regenerating your API key

For more troubleshooting help, see our MCP troubleshooting guides.

What Your AI Can Do

Read Information

Your AI assistant can retrieve:

Task details - Full description, comments, dates, assignees
Board overview - Columns, task counts, project context
Project information - Client, status, related boards

Take Actions

Your AI assistant can perform:

Create tasks - Add new tasks with descriptions, dates, and assignments
Update tasks - Change status, move between columns, update details
Add comments - Document work done or leave notes
Track time - Start and stop time tracking on tasks
List and search - Find tasks, projects, and boards

Example Conversations

General Productivity (Claude Desktop)

You: "What tasks are due this week?" AI: Lists your upcoming tasks with due dates and projects

You: "Create a task to follow up with Acme Corp about the proposal" AI: Creates a new task and confirms the details

You: "Start tracking time on my current task" AI: Starts the time tracker on your active task

Development Workflow (Cursor)

You: Share a Corcava task link "Help me implement this feature" AI: Reads the task requirements and helps you write the code

You: "Add a comment to task #123 that I've completed the API changes" AI: Adds the comment documenting your work

You: "What are the acceptance criteria for this task?" AI: Retrieves and displays the task description and comments

Available Tools

Tool	Description
`list_tasks`	Search and filter tasks by project, board, or keyword
`get_task`	Get full details of a specific task
`create_task`	Create a new task with title, description, dates
`update_task`	Update task details or move to different column
`delete_task`	Remove a task permanently
`list_projects`	List all projects you have access to
`get_project`	Get project details and related boards
`list_boards`	List boards, optionally filtered by project
`get_board`	Get board details including columns
`list_task_comments`	Get all comments on a task
`add_task_comment`	Add a comment to a task
`start_time_tracking`	Start tracking time on a task
`stop_time_tracking`	Stop current time tracking session
`get_tracking_status`	Check if time tracking is active

Security Notes

Your API key provides full access to your Corcava data - keep it secure
Never share your API key or commit it to version control
You can deactivate or delete API keys anytime in Settings → Integrations
Each API request is scoped to your team's data only

Troubleshooting

"Authorization failed" or "Invalid API key"

Double-check you copied the full API key
Ensure the key is active in Settings → Integrations → Public API
Make sure you're using the Bearer prefix followed by a space before the key

AI doesn't see Corcava tools

Restart your AI assistant after adding the configuration
Verify the MCP server URL is correct: https://app.corcava.com/mcp
Check that the JSON configuration is valid (no syntax errors)

"Connection refused" errors

Verify your internet connection
Check if Corcava is accessible in your browser
Try regenerating your API key

Support

Need help? Contact our support team or check the Public API documentation for more details about the underlying API.