skip to content
start free

// product

featuressecurityextensionschangelog

// solutions

for wordpressself-hostingfor agencies

// resources

docsapi referenceblogroadmap
pricing
start free

// blog

Connect your AI assistant to your boards with MCP

Let Claude or Cursor read and update your tasks for you. Here is what MCP is, how to set it up in a few minutes, and how to stop your AI client asking permission on every step.

You can connect an AI assistant, like Claude or Cursor, straight to your Coalface Tasks workspace. Once it is set up, you can ask it things like “what is on my board this week?” or “add a task to write the launch email” and it will do it for you, right there in your boards.

This guide covers what that connection is, how to turn it on, and how to make it smooth to use day to day. No deep technical knowledge needed.

What is MCP?

MCP stands for Model Context Protocol. That is a mouthful, so here is the plain version: it is a standard way for an AI assistant to use an outside tool.

In our case, the outside tool is your Coalface Tasks workspace. Turning on MCP gives your AI client a set of buttons it can press on your behalf, like “list boards”, “create task” or “add a note”. The assistant decides which button to press based on what you ask it in plain English.

A few things worth knowing up front:

  • The AI runs on your side, using your own AI plan. We do not run it or pay for it. Your client connects to your workspace and does the work there.
  • It can only do what you allow. You create a key and choose exactly what it can touch. More on that below.
  • Your Vault is never exposed. Secrets you keep in the Vault are off limits to the assistant, always.

Turning it on

There are two steps: switch the feature on, then create a key.

1. Enable the extension. Go to Settings, then General, then Extensions, and turn on AI tools (MCP). It is off by default.

2. Create an API key. Go to Settings, then API. Create a new key and choose the scopes you want the assistant to have. A scope is just a permission, for example “read tasks” or “read and write tasks”. Give it only what you need. Your key starts with ctk_. Copy it somewhere safe now, because you will not be able to see it again.

That same API page then shows you the connection details, ready to copy.

Connecting your client

You will need two things from the API page: the endpoint (a web address ending in /api/mcp) and the key you just made.

If you use Claude Code, run this in your terminal, with your real key in place of ctk_YOUR_API_KEY:

claude mcp add --transport http --scope user coalface-tasks https://YOUR-WORKSPACE/api/mcp \
  --header "Authorization: Bearer ctk_YOUR_API_KEY"

The --scope user part makes the connection available in all your projects. Drop it if you only want it in the project you are in right now.

If you use Claude Desktop or Cursor, add this to your client’s config file, again with your real key:

{
  "mcpServers": {
    "coalface-tasks": {
      "url": "https://YOUR-WORKSPACE/api/mcp",
      "headers": { "Authorization": "Bearer ctk_YOUR_API_KEY" }
    }
  }
}

Restart your client and you are connected. Ask it “list my boards” to check it is working.

What your assistant can do

Once connected, your assistant has a tidy set of tools. It picks the right one for what you ask. Here is the full list in plain terms.

Reading things

  • See all your boards and their columns
  • List tasks on a board or in a column
  • Open a single task, with its checklist progress and, if you track time, how long has been logged
  • List the checklist items on a task
  • List the notes and comments on a task
  • List the files attached to a task
  • List your labels and the people in your workspace

Creating and changing things

  • Create a task, and seed its checklist in the same step
  • Update a task: change its title, description, priority, due date, or move it to another column
  • Snooze a task until a date, or archive it to clear it off the board
  • Mark a task done
  • Add, rename, tick off, or reorder checklist items
  • Add a note or comment
  • Attach a file, such as a plan, a design, or a document
  • Add or remove a label on a task

A couple of deliberate limits, for your safety:

  • There is no delete. To clear a task away, the assistant archives it. Nothing is ever permanently removed by the AI.
  • Time tracking is read only. The assistant can tell you how much time has been logged, but it does not log time itself.

The exact tools you see also depend on which extensions you have switched on. If you do not use time tracking, for example, its tools simply will not appear.

Fewer permission prompts

By default, some AI clients ask you to approve every single action. That gets tiring fast, especially when the assistant is doing a run of small steps. Since you already chose what the key can do when you made it, you may be happy to pre-approve the tools.

This part is about your AI client’s own settings, not Coalface Tasks. The example below is for Claude Code, which reads a settings.json file.

The simple option: trust the whole connection. This stops the prompts for every Coalface Tasks tool:

{
  "permissions": {
    "allow": ["mcp__coalface-tasks"]
  }
}

Because our tools never delete anything, trusting the whole connection only ever lets the assistant read and create or update, which is a fair level of trust for your own data.

The careful option: auto approve reading, still ask before changes. This lets the assistant look around freely but check with you before it writes anything:

{
  "permissions": {
    "allow": [
      "mcp__coalface-tasks__list_boards",
      "mcp__coalface-tasks__list_tasks",
      "mcp__coalface-tasks__list_columns",
      "mcp__coalface-tasks__get_task",
      "mcp__coalface-tasks__list_attachments"
    ],
    "ask": [
      "mcp__coalface-tasks__create_task",
      "mcp__coalface-tasks__update_task",
      "mcp__coalface-tasks__add_note",
      "mcp__coalface-tasks__add_attachment"
    ]
  }
}

A few tips:

  • Put these settings in your project’s .claude/settings.json to apply them to one project, or in your home folder’s ~/.claude/settings.json to apply them everywhere.
  • You can also run /permissions inside Claude Code to manage all this from a menu, without editing files by hand.
  • One catch: shortcuts like mcp__coalface-tasks__* do not currently work. List each tool by its full name, or trust the whole connection with the single line above.

The short version

  1. Turn on AI tools (MCP) in Settings, then General, then Extensions.
  2. Make an API key in Settings, then API, and choose its scopes.
  3. Paste the connection command or config into your AI client.
  4. Optional: add an allow rule so you are not asked to approve every step.

That is it. From then on your assistant can help run your boards in plain English, within the limits you set.

← all posts