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 choose OAuth or an API key for your client
How to connect Corcava as a remote MCP server
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.

Two ways to connect

Corcava supports two authentication paths. Pick the one your client supports:

Path	Use for
OAuth Custom Connector (recommended)	claude.ai web, Claude Desktop's "Custom Connector" UI, ChatGPT MCP — any client that asks you to "Add a custom connector" with just a URL
API Key (Bearer token)	Cursor, Windsurf, Continue, and other clients that explicitly support remote MCP URLs with static headers

Both paths give the AI the same set of tools and the same access scope (your Corcava data, no one else's).

Path A — OAuth Custom Connector (Claude, ChatGPT)

If your client offers an "Add custom connector" or "Connect MCP server" button that only asks for a URL, use this path. There is no API key to copy.

In your AI client, open the connector / MCP setup screen.
Enter the URL: https://app.corcava.com/mcp
The client opens a Corcava browser window. Sign in to Corcava if you aren't already.
Review the Authorize screen — it shows which client is asking for access and what it can do (read tasks, create tasks, track time, etc.). Click Authorize.
The browser returns you to your AI client; the connector is now active.

For Claude, individual Pro and Max users can add their own custom connector. On Team and Enterprise plans, an Owner or Primary Owner first adds the organization connector under Organization Settings → Connectors; each member then selects Connect and authorizes their own Corcava account.

You can revoke this connection at any time from Settings → Integrations → AI Assistants → Connected AI Clients.

Path B — API Key (supported remote-client configurations)

Use this for clients that take a static JSON config and a Bearer token:

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.

API-key configuration

Clients that explicitly support remote MCP URLs with static headers need these two pieces of information:

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 API-key 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.

Claude Desktop: Corcava is a remote server. Use Customize → Connectors to connect it. Individual Pro and Max users can select Add custom connector; on Team and Enterprise plans, an Owner or Primary Owner adds it for the organization. Claude's claude_desktop_config.json is the documented path for local servers launched with command and args, not for a direct Corcava url and headers entry.

Client-Specific Setup

Each AI assistant has its own connection interface or configuration 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 identifies whether to use a remote custom connector or a supported static configuration, then provides platform-specific instructions and troubleshooting.

Verification Checklist

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

✅ Step 1: Connection method

For OAuth custom connectors:

Corcava was added using https://app.corcava.com/mcp
Browser authorization completed for the intended Corcava workspace
Corcava is enabled for the current conversation

For supported API-key configurations:

The configuration file exists in the location required by that client
JSON syntax is valid
Endpoint URL is exactly https://app.corcava.com/mcp
Authorization header uses Bearer YOUR_API_KEY
The API key is active and contains no copied whitespace

✅ Step 2: Reload the connection

Corcava is enabled in a new conversation after OAuth setup
A static-configuration client was reloaded or restarted after its file changed

✅ 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:

Confirm Corcava is enabled for the current conversation
Reconnect an OAuth custom connector
For API-key clients, validate the local configuration and reload the client

If you get "Authorization failed":

Reconnect OAuth if the client uses browser authorization
For API-key clients, verify the key is active and the header uses Bearer YOUR_API_KEY

If connection fails:

Verify your internet connection
Check if https://app.corcava.com is accessible in your browser
Reconnect OAuth, or replace the key only if the client uses static API-key authentication

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

A static API key grants access to Corcava data in its team scope—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"

Reconnect Corcava if the client uses OAuth
For static configurations, ensure the key is active and the header uses Bearer YOUR_API_KEY

AI doesn't see Corcava tools

Confirm Corcava is enabled for the current conversation
Reconnect the OAuth custom connector
For static configurations, verify the URL, validate the file locally, and reload the client

"Connection refused" errors

Verify your internet connection
Check if Corcava is accessible in your browser
Reconnect using the authentication method supported by the client

Support

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