External Integrations
Configure PrimeTask's deep links, MCP server for AI agents, and the unified audit log - plus connect external tools like Claude Code, Cursor, Apple Shortcuts, Alfred, and Raycast.
The External Integrations settings card is where you let other tools talk to PrimeTask. That includes:
- Deep links (
primetask://URLs) that let you create tasks, start timers, and jump to pages in PrimeTask from launchers like Apple Shortcuts, Alfred, Raycast, command-line scripts, or any note-taking app that supports custom URL schemes - The MCP server, which lets AI coding agents (Claude Code, Cursor, Claude Desktop, LM Studio, and any other MCP-compatible client) read and write PrimeTask data on your behalf
- The unified audit log, which records every external command that hits PrimeTask via either path so you can review, export, or investigate
Everything on this card runs locally on your machine. Deep links go through the operating system's URL handler; the MCP server listens on your own computer, not a remote service. PrimeTask does not send your data anywhere when you enable these integrations. However, the AI tools you connect to the MCP server may send the data they read to their own cloud providers as part of how they operate - that's outside PrimeTask's control, and the card's first-time consent flow spells this out clearly.
Enable only tools you trust
When you connect an external AI tool to PrimeTask's MCP server, that tool gains programmatic access to your tasks, projects, and (if you turn on write permission) the ability to create, change, and delete data. Only connect tools you've chosen deliberately. If you give an agent write access, assume it could make destructive changes - back up before you experiment. See Data Management.
Both integrations are in active development
Deep Links and MCP Server are both marked Beta. They work well in day-to-day use, and the first time you turn either one on, PrimeTask shows a consent explainer so you understand what you're enabling before anything is exposed.
What you can do
Turn on the `primetask://` URL scheme
so any app, launcher, or script on your machine can create tasks, start timers, and jump around PrimeTask
Register the URL scheme with your operating system
primetask:// links actually open PrimeTask when clickedBrowse every deep link command
from the Command Explorer - search, filter, and copy the right command for your workflow
Turn on the MCP server
so AI agents like Claude Code and Cursor can read and write PrimeTask data
Control what the AI can do
read-only by default; write access is a separate opt-in
Limit which Spaces the AI can touch
all Spaces, or a short list you pick
Pick a tool profile
from minimal (just tasks) to full (everything), plus CRM and Custom Fields profiles on Pro
Copy ready-made config snippets
for Claude Code, Cursor, Claude Desktop, LM Studio, and the stdio transport
Regenerate your MCP API key
when you want to rotate credentials or lock out an old client
Review the audit log
every external command with timestamps, results, and errors
Search, filter, and export the audit log
to JSON or CSV for review or investigation
Clear the audit log
when you want a fresh start
How to open External Integrations settings
- Settings card: Open Settings from the sidebar, then open the External Integrations card.
- Settings search: Open Settings and type external, mcp, deep link, ai, or shortcut.
- Command palette: Press ⌘+K (or Ctrl+K), type external or mcp, and pick the entry.
The card has two big sections - Deep Links and MCP Server - plus an Audit Log button that opens a full-screen log viewer. Both sections are off by default.
Things worth knowing
Deep Links - let other apps talk to PrimeTask via primetask://
Deep links are short URLs that tell PrimeTask to do something when clicked. They look like primetask://tasks/create?spaceName=Work&title=Finish%20the%20proposal. Any app, launcher, script, or note-taking tool that can open a URL can use them.
Turning on Deep Links is a two-step setup:
Step 1
Enable External Integrations. This is the master switch. The first time you turn it on, PrimeTask shows a consent explainer.
Step 2
Register the protocol handler. The Register button tells your operating system that primetask:// URLs belong to PrimeTask. After you click it, clicking a deep link anywhere on your computer opens PrimeTask and runs the command. You can Unregister at any time to remove the association.
The two steps are independent by design - you can turn the feature on for a minute to test something, leave the OS-level registration alone, and turn it back off without changing the system-wide handler. Most people will register once and forget about it.
Browsing every available command
The Commands button opens a Command Explorer that lists every deep link command PrimeTask supports, grouped by category - task, timer, navigation, and open. You can search by command name, description, or parameter, filter by category, and click any command to copy a ready-to-use terminal command (with your active Space prefilled) to your clipboard. The Explorer also shows commands that aren't yet available, so you can see what's coming.
Deep links work on both macOS and Windows. The card's quick-test helper shows the right terminal syntax for each platform (open "primetask://..." on macOS, start primetask://... on Windows).
Deep links require a Space
Every command has to know which Space it's acting on. The Space name (or ID) is a required parameter on every deep link, which prevents a command from accidentally touching the wrong Space just because you happened to be active in another one. If a link omits the Space, it simply doesn't run. This is a safety rail - don't try to work around it.
External tools that work well with deep links
Apple Shortcuts, Alfred, Raycast, Keyboard Maestro, BetterTouchTool, shell scripts, Obsidian templates, Craft's custom buttons, and anything else that can open a URL - all of them can fire deep links at PrimeTask. See External Integrations for setup walkthroughs for the most popular launchers.
MCP Server - connect AI agents to PrimeTask
PrimeTask ships with a local MCP (Model Context Protocol) server that lets AI coding agents - Claude Code, Cursor, Claude Desktop, LM Studio, Windsurf, and anything else that speaks MCP - read from and (optionally) write to your PrimeTask data. The server runs on your own computer, not remotely; agents connect to it through a local connection PrimeTask sets up.
Like Deep Links, MCP is off by default and turning it on shows a consent explainer. The explainer is worth reading: it's where PrimeTask makes clear that while the server itself is local, any AI tool you connect may still send your data to its own cloud for processing. That's a property of how those tools work, not something PrimeTask can prevent.
Read and write are separate permissions
Once MCP is on, two toggles control what agents can do:
- Read - on by default. Agents can list, search, and view tasks, projects, notes, and other content in your allowed Spaces. Nothing is modified.
- Write - off by default. Agents can create, change, complete, and delete data. Turn this on only for agents you trust with destructive operations.
You can run MCP in read-only mode for a while to see what an agent actually does with your data before ever giving it write permission. That's the recommended starting point.
Start read-only, add write later
A read-only agent can still do a lot - summarise your backlog, pull daily standups from tasks, draft a weekly review. You may never need write access at all. If you do enable write, make sure you have a recent backup from Data Management first.
Which Spaces can the agent see?
The Space access control has two settings:
- All Spaces - the agent can see and switch between every Space you own
- Selected only - you pick specific Spaces with checkboxes. Any Space you don't tick is invisible to the agent.
Selected only is the default. A typical setup is to include your Work Space and exclude anything personal - agents then can't see your private Spaces at all, even if they ask.
Tool catalog - profiles and per-category control
PrimeTask's MCP server exposes dozens of tools for manipulating tasks, projects, notes, custom fields, CRM records, and more. You don't usually want all of them exposed to every agent, so the card lets you pick a profile:
- Full - every available tool, across every category. Best for general-purpose agents.
- Core Tasks - the task, project, note, goal, time tracking, and focus toolset. No CRM, Custom Fields, or canvas-specific tools.
- Projects - a project-planning subset with dependencies, team, and milestones.
- PrimeFlow - canvas-focused. See PrimeFlow Overview.
- Minimal - tasks, checklist, utility. The smallest possible surface for lightweight clients.
You can also expand the Customise categories area and tick or untick individual categories to build your own profile. As soon as you change any checkbox, PrimeTask remembers the custom configuration.
Two additional profiles - CRM and Custom Fields - are available on the Pro tier. They include the CRM toolset (contacts, companies, activities, CRM tasks) and the Custom Fields toolset (field definitions, rollups, tabs) respectively. The same toolsets can also be toggled individually inside Customise categories when you're on Pro. See License Settings to upgrade.
The API key and Quick Setup
When you turn MCP on, PrimeTask generates an API key automatically. You'll see it on the card - masked, with Copy and Regenerate buttons next to it.
- Copy puts the full key on your clipboard so you can paste it into an AI tool's config.
- Regenerate replaces the old key with a new one. Any client still using the old key will stop working until you update its config.
**Warning - Regenerate invalidates every existing client: Clicking Regenerate** immediately replaces your API key. Every AI tool you've connected - Claude Code, Cursor, Claude Desktop, anything else - will fail to authenticate until you update each tool's config with the new key. Only regenerate when you actually want to rotate the credential or cut off an old client. There's no undo.
Below the API key, the card has Quick Setup buttons for the most common AI tools - Claude Code, Cursor, Claude Desktop, LM Studio, and the stdio transport. Each button copies a ready-to-paste config snippet (with your API key already filled in) to your clipboard and tells you where to save it. Use whichever button matches your tool, paste the config into its MCP settings file, and restart the tool - connection is automatic from there.
For tools the Quick Setup doesn't cover, see bring-your-own-ai for the generic connection details.
MCP runs on the active Space by default
When an agent connects, it sees whichever Space you currently have active in PrimeTask's sidebar. If the agent needs to work in a different Space, it calls a built-in switch_space tool - which not only gives the agent access to the new Space but also switches your visible PrimeTask UI to match. This is deliberate: you always see where the agent is working.
Audit Log - every external command, recorded
The Audit Log is a unified history of every external command that reached PrimeTask - deep links and MCP calls. Click the Audit Log button on the card to open a full-screen viewer with:
- Search across command names, parameters, and error messages
- Status filter - all, successful, or failed only
- Date filter - all time, today, last 7 days, last 30 days
- Pagination for long histories
- Export to JSON or Export to CSV - exports respect your current filters, so you can export just the failures from last week if that's what you need
- Clear - wipes the entire log. This is irreversible and asks for confirmation before it runs.
Each entry shows the timestamp, command name, parameters, whether it succeeded, the error message (if any), and the source (deep_link or mcp). This is genuinely useful for figuring out what an agent did, diagnosing a broken Alfred workflow, or auditing which commands external tools actually use.
The audit log doesn't include sensitive response data
Responses from tools that might contain secrets (PIN states, passwords, encryption-related fields) are stripped before the log is written. What's recorded is the command that was called, its parameters, and whether it succeeded - not the full response payload.
Configuration is per-device, not synced
External Integrations settings live on each device independently. Enabling MCP on your Work Mac doesn't enable it on your Home Mac - each machine decides for itself whether to run the server, which Spaces to expose, which permission mode to use, and which tool profile is active. Your tasks and projects still sync between devices through the Space's own sync; it's only the integration configuration that stays local.
The API key is also per-device. Each machine generates its own, and regenerating on one doesn't touch the other. This is by design - compromising one device's integrations doesn't compromise all of them.
Windows vs macOS
The card works the same way on both platforms. The primetask:// URL scheme registers with each operating system natively, and the MCP server runs on both. The only surface difference is the quick-test terminal helper, which shows open syntax on macOS and start syntax on Windows. Both platforms support every feature in this card.
Common questions
"I turned on MCP but my AI tool can't connect."
Check three things in order:
"Can I run MCP in read-only mode and still get useful work out of an agent?"
Yes, and honestly it's the right starting point. A read-only agent can search your backlog, summarise overdue tasks, draft a daily standup from task updates, write a weekly review from what you completed, pull project status reports, and more. You don't need write access for any of that. Enable write access only when you actually want the agent to modify data for you.
"I want to give a specific agent access only to one Space."
Set Space access to Selected only, tick the one Space you want exposed, and leave everything else unticked. From that point on, the agent can't see or touch any other Space - it literally can't list them. This is the right setup for experimenting with new agents or letting a less-trusted tool work in a sandbox Space.
"I regenerated the API key by mistake. How do I roll back?"
You can't. Regeneration is destructive and immediate - the old key is gone. Your only path forward is to copy the new key from the card and update each connected tool's config with it. The tools themselves don't lose any of their saved state; they just need the new key to reconnect.
"Can I see what an agent did to my data?"
Yes. The Audit Log records every command an agent ran (via MCP) and every deep link that fired, with timestamps, parameters, and success/failure status. Open it, filter by source (mcp), filter by date if you know roughly when, and you'll see the full call history. Export to JSON if you want to analyse it externally.
"The card shows a CRM profile and a Custom Fields profile that I can't pick. Why?"
Those are Pro-tier profiles. They bring in MCP tool categories (CRM contacts, companies, activities, CRM tasks, custom field definitions, rollups, etc.) that are part of the Pro license. To unlock them, upgrade from License Settings.
"Does turning on MCP mean my data goes to Anthropic / OpenAI / whoever made my AI tool?"
Not via PrimeTask. The MCP server runs locally - it doesn't send anything to a remote service. However, the AI tools you connect to the MCP server (Claude Code, Cursor, etc.) are separate products made by different companies. When those tools read data from PrimeTask through MCP, they typically send that data to their own cloud providers for processing as part of how they work. That's how AI coding assistants work in general, and it's outside PrimeTask's control. The consent dialog you see when you first enable MCP spells this out; read it carefully and only connect tools you trust with your data.
"How do I let an external tool know which Space I'm in right now?"
You don't have to - the MCP server always operates on your currently active Space by default. For deep links, every command has a required spaceName parameter that you fill in yourself (or that the Command Explorer prefills with your active Space when you copy a command). In both cases, nothing runs against the wrong Space by accident.
"I'm worried about security. What's the best hardening setup?"
Reasonable defaults:
Where to go next
| If you want to… | Read this |
|---|---|
| Go deeper on the MCP server as a feature | bring-your-own-ai |
| Go deeper on deep links and external tools | External Integrations |
| Configure Apple Calendar and Apple Reminders | Integrations Settings |
| Upgrade to unlock CRM and Custom Fields MCP tools | License Settings |
| Lock PrimeTask behind a PIN | Security Settings |
| Back up your data before experimenting | Data Management |
| Understand per-Space isolation | Spaces Overview |
| Trigger automations with keyboard shortcuts | Automations Settings |
| Browse all settings cards | Settings Overview |