Bring Your Own AI

PrimeTask doesn't subscribe you to an AI model. It doesn't lock you into one vendor. Instead, it speaks MCP - the Model Context Protocol - so the AI tool you already use can read and interact with your workspace directly. ChatGPT desktop, OpenAI Codex, Claude Code, Cursor, LM Studio, Claude Desktop, and any other MCP-compatible client can connect.

The server runs on your computer. Your data stays on your computer. You choose what the agent can see, what it can change, which Spaces it can touch, and which tools it can call. Every command is written to an audit log you can review.

For the Integrations category hub, see Integrations Overview. For what the agent can do specifically on PrimeFlow canvases, see PrimeFlow and MCP.

What you can do

Quick Start

1. Enable the server

2. Connect Your AI Tool

ChatGPT desktop and OpenAI Codex

One setup connects PrimeTask to both normal ChatGPT and Codex conversations in the ChatGPT desktop app.

Other MCP clients

Streamable HTTP (recommended):

Use the Streamable HTTP option in Quick Setup to copy the config:

{
  "primetask": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "http://localhost:24842/mcp",
      "--header",
      "Authorization:${PRIMETASK_MCP_AUTH}"
    ],
    "env": {
      "PRIMETASK_MCP_AUTH": "Bearer pt_mcp_your_key_here"
    }
  }
}

Your key goes in the env section, never in args. Everything in args is visible to other programs running on your computer, so a key placed there is on show; the env section keeps it out of sight. Copy the setup from Quick Setup rather than typing it by hand and this is handled for you.

Paste into your AI tool's MCP config file:

• Claude Code: ~/.claude.json under projects → your-project → mcpServers
• Cursor: ~/.cursor/mcp.json
• LM Studio: MCP server settings (JSON config)
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json under mcpServers

Stdio (alternative):

Use the Stdio option to copy the config. The AI tool launches PrimeTask as a separate process:

{
  "primetask": {
    "type": "stdio",
    "command": "/Applications/PrimeTask.app/Contents/MacOS/PrimeTask",
    "args": ["--mcp-server"]
  }
}

3. Start Using

Once connected, your AI tool can access your tasks, projects, CRM, and more. Try asking:

• "What are my overdue tasks?"
• "Create a task called Review proposal with high priority"
• "Start a 30-minute focus session on Write documentation"
• "Show me the status of the Website Redesign project"

Security & Permissions

Authentication

Every HTTP request requires a Bearer token. The token is auto-generated when you first enable MCP and shown in Settings - copy it along with the config.

Regenerate the token from Settings when you want to rotate it. Update your AI tool's config with the new token afterwards.

Read / Write Permissions

• Read (on by default) - list, search, and view tasks, projects, CRM data
• Write (off by default) - create, update, delete, complete tasks and other data

Enable write permissions in Settings → MCP Server → Write toggle.

Space Access

Control which spaces AI agents can access:

• All spaces - agent can access any space
• Selected only - choose specific spaces from the checkbox list

Requests targeting a space not in the allowed list are rejected with a clear error.

Audit Logging

Every MCP tool call is logged. View the audit log in Settings → External Integrations → Audit Log. Each entry shows the tool name, parameters, timestamp, and whether it succeeded or was blocked.

Sensitive Field Filtering

PrimeTask automatically strips sensitive fields from all MCP responses: PIN hashes, encryption keys, passwords, secrets, and tokens are never exposed.

The PrimeTask Lock Screen

If you lock PrimeTask, your agent stops with it. Locking the app covers your agent as well as your screen, so a connected AI tool can't keep reading and changing your work while you're away from your desk. It doesn't disconnect while it waits, and it tells you PrimeTask is locked instead of reporting a fault. Unlock and it carries on from where it stopped.

If you'd rather it kept working while you're away, open Settings → Security and turn on the switch for letting AI agents work while locked. It's off unless you turn it on, and PrimeTask explains what it means before it takes effect. See Security Settings.

Feature Gating

Some tools require a Pro licence.

Tool Catalog & Profiles

PrimeTask exposes more than 100 tools, which can be a lot for AI clients with limited context windows. The Tool Catalog in Settings lets you control which tools are available, using either preset profiles or per-category toggles.

Why profiles exist

Some AI tools (like LM Studio or smaller local models) perform better with a focused set of tools rather than the full catalog. Profiles let you expose only the tools relevant to your workflow, reducing noise and improving tool selection accuracy.

Preset Profiles

Select a profile card to instantly configure the tool catalog:

Profiles marked (Pro) are part of the Pro tier - see License Settings to upgrade.

Per-Category Customisation

Click "Customise categories" below the profiles to expand individual category toggles. Each toggle enables or disables a group of related tools (e.g. "Notes", "Focus", "Time"). Toggling any category manually switches the profile to Full (custom configuration).

Some categories (CRM, Custom Fields, Dependencies, Team) are part of the Pro tier.

Naming your assistant

Below the categories you can set the name your assistant writes under when it comments on a task. It defaults to Agent. A thread that mixes people and an assistant is much easier to read a month later when it says which was which, so pick something you will recognise.

See Task Comments for what it can do in a thread, and what it cannot.

Applying changes

• Streamable HTTP: Profile changes take effect on the next client reconnect - no app restart needed.
• Stdio: The tool list is set at process launch. Changing profiles requires the AI tool to reconnect.

Tools Reference (more than 100 tools)

Changes made through MCP appear in the relevant open PrimeTask views automatically. After a PrimeTask update adds or changes tools, fully quit and reopen PrimeTask, then reconnect your AI tool so it receives the current catalog.

Spaces (4 tools)

Tasks (9 tools)

Name resolution: project_id accepts a project name or UUID. assignees accepts display names or member IDs.

Apple Calendar and Reminders (macOS): Ask your agent to add a task to your reminders or your calendar and it can, using sync_to_reminders and sync_to_calendar. Both integrations are set up in Settings and each syncs one space, so your agent checks get_system_info first and tells you if an integration is switched off, or if the task belongs to a different space than the one you sync. Reading a task back afterwards shows whether the reminder or event was actually created. See Apple Reminders and Calendar.

Subtasks & Dependencies (4 tools)

Checklist (3 tools)

Projects (8 tools)

get_project_stats returns: weighted progress across tasks/milestones/goals/CRM, per-bucket breakdown (progress, count, completed), overdue count, status/priority distribution, and project timeline.

get_project_health returns: health status (on_track/at_risk/behind/critical), progress vs expected, trend (improving/stable/declining), overdue task count, next milestone with progress, and up to 5 actionable recommendations. Same calculation as the in-app Health Assistant.

Notes (6 tools)

Goals & Milestones (6 tools)

Linking tasks to milestones: Use update_task with milestone_id to link a task to a milestone (or null to unlink).

Project Team (3 tools)

Note: Linking CRM contacts/companies as team members requires Pro. Manual members work on Standard.

CRM - Contacts (7 tools) - Pro

CRM - Companies (10 tools) - Pro

Several records at once: The plural tools take a list and apply each entry on its own, so one bad entry does not stop the rest. You get back how many were requested, how many worked, and what was wrong with any that did not, so your agent can fix those and try again. Useful when you hand over a spreadsheet of contacts. Up to 100 records per request.

Shared and isolated CRM: Leave project_id out to work with shared CRM. Provide a project name or ID to work inside that project's isolated CRM. For a complete search across shared and isolated CRM, use include_isolated when listing contacts or companies.

Name resolution: Contact, company, and project references accept a name or ID. Use an ID when more than one record has the same name.

CRM - Tasks (4 tools) - Pro

CRM - Activities (4 tools) - Pro

CRM - Message Templates (7 tools) - Pro

Reusable LinkedIn outreach templates with placeholders ({first_name}, {company}, fallbacks like {first_name|there}, namespaced like {company.industry}). The agent can build your library, personalise messages for any contact, and optionally log the activity on the contact's timeline so success rates stay accurate.

Tags, Statuses, Priorities (3 tools)

Time Tracking (4 tools)

Focus Mode (4 tools)

PrimeFlow (11 tools)

bulk_canvas_update is the recommended way to build complex canvases. Use ref on nodes and "ref:<refName>" in edge source/target to reference nodes created in the same batch - no need to know IDs ahead of time. Mind map nodes get default colors automatically.

27 supported node types:

Node data examples:

Documentation node:

{"type": "documentation", "data": {"title": "API Docs", "content": "<h2>Auth</h2><p>Use Bearer tokens</p>", "nodeType": "documentation"}}

Mermaid diagram from text:

{"type": "mermaid", "data": {"label": "User Flow", "code": "graph TD\n  A[Login] --> B{Auth?}\n  B -->|Yes| C[Dashboard]", "nodeType": "mermaid"}}

Portal (link to another canvas):

{"type": "portal", "data": {"label": "Backend Design", "targetCanvasId": "canvas-id", "targetCanvasName": "Backend", "nodeType": "portal"}}

Mind map node:

{"type": "centralTopic", "data": {"label": "Project Overview"}}

The agent can build interconnected canvas systems - create multiple canvases, add mind maps, documentation, diagrams, and link them with portal nodes and edges.

Custom Fields (11 tools) - Pro

Field Values:

Field Definitions:

Field Tabs (per-project):

Supported field types: text, textarea, number, currency, date, datetime, dropdown, multi_select, checkbox, rating, progress, url, email, phone, relationship.

Automatic tab updates: When an agent creates a field, PrimeTask adds it to existing Project Fields tabs whose Show As mode matches the field's scope. Changing a field's scope also updates the matching tabs. The agent does not need to know every project or tab name.

Relationship fields support bidirectional links and rollup aggregations (sum, average, minimum, maximum, count) across linked entities. Setting or clearing a bidirectional value keeps both sides of the relationship in step.

Financial setup example:

Quick Notes (4 tools)

Reminders (6 tools)

spec formats: relative offsets (5m, 30m, 1h, 2h, 1d, 1w), clock times (9am, 9:30am, 14:30, 5pm), or full ISO timestamps (2026-05-20T14:30:00.000Z). The agent doesn't need to know whether the task has a due date. The handler picks the right anchoring automatically. On a task with no due date, a relative offset like 30m means "30 minutes from now".

Reminders in shared spaces are personal. When the agent sets a reminder on your behalf, it's stamped with your identity, so only your devices fire. Teammates in the same space won't be paged.

Comments (4 tools)

Comments your assistant writes are labelled as its own. They carry the agent name you choose in Settings → External Integrations, so a thread always makes clear which entries were written by a person and which by an assistant.

Your assistant can only change its own comments. It can read everything on a task, but editing and deleting are limited to comments it wrote itself, so your own words are never rewritten. You can edit or delete anything in the thread, including your assistant's comments.

Everything written here behaves like a comment you typed. Markdown renders, links to videos, posts and images turn into previews, mentioning another task links the two together, and the comment appears in search and in the comment count on your task list.

Utility (4 tools)

Documentation search lets AI agents answer questions about PrimeTask features using the built-in docs. Ask your agent "How do I use Quick Add?" or "Show me the docs for recurring tasks" - it searches PrimeDocs and returns the relevant article.

Getting the best results

Your agent works well from plain instructions. These few habits make a noticeable difference.

Use everyday names, not IDs

Say "link Sarah Chen to Quantum Ventures" rather than hunting for identifiers. Contacts, companies, projects, statuses, tags and assignees are all matched by name. Reach for an ID only when two records share a name and you need to be specific.

Name the project when you work inside one

A project can keep its own separate CRM. Those contacts and companies do not appear in your main lists, so tell your agent which project you mean: "add a note to Sarah Chen in the Zenith project". To count or search everything at once, ask for shared and project records together.

Ask for many at once

Handing over a list of twenty contacts works better as one request than twenty. Your agent reports what went in and what did not, so you can fix a few rows rather than starting over.

Dates can be written your way

Type dates however you normally would. Your agent reads them the way you have set PrimeTask to display them, so a day-first date is not mistaken for a month-first one. Writing the year first, as in 1985-04-23, is always understood and never ambiguous.

Say what should happen next

Requests like "add this to my reminders" or "put it on my calendar" work on macOS once those integrations are set up. If one is switched off, or the task belongs to a different space than the one you sync, your agent tells you rather than quietly skipping it.

Ask it to check its work

Your agent can read records back, so ask it to confirm. "Add the contact, then show me what you saved" catches a misunderstanding immediately rather than later.

Prompts (5 templates)

MCP prompts are pre-built templates that give AI agents structured context from your workspace. The agent calls prompts/get and PrimeTask gathers the relevant data automatically.

Example Usage

Ask your AI agent:

• "Use the daily_standup prompt to generate my standup"
• "Run project_status for Website Redesign"
• "Help me triage overdue tasks"

You can also browse prompts in the Command Explorer (Settings → External Integrations → Commands → Prompts tab).

Transport Options

Streamable HTTP (recommended)

• Runs inside the PrimeTask app - no separate process needed
• Multiple AI tools connect simultaneously
• Auto-starts when MCP is enabled
• Port: 24842 (fixed, localhost only)
• Bearer token authentication via mcp-remote bridge
• Uses npx mcp-remote to bridge between AI tools and the HTTP server

Stdio

• AI tool launches PrimeTask as a separate process (--mcp-server)
• One client per process
• No authentication needed (local pipe)
• Good for CLI-based tools

Examples

Create a task with a checklist

AI: "Create a task called 'Sprint Planning' with high priority in the API project, 
     with a checklist: review backlog, assign stories, estimate points"

The agent calls create_task with:

{
  "name": "Sprint Planning",
  "priority_id": "high",
  "project_id": "API Project",
  "checklist": [
    {"text": "Review backlog"},
    {"text": "Assign stories"},
    {"text": "Estimate points"}
  ]
}

Start a focus session

AI: "Start a 45-minute focus session on the Design Review task"

The agent calls start_focus with:

{
  "task_id": "Design Review",
  "duration": 45
}

Add a task dependency

AI: "Make 'Write tests' depend on 'Implement API'"

The agent calls add_dependency with:

{
  "task_id": "Write tests",
  "prerequisite_id": "Implement API"
}

Set a reminder

AI: "Remind me about the John Doe call in 30 minutes"

The agent calls set_reminder with:

{
  "task_id": "John Doe call",
  "spec": "30m"
}

Log a CRM activity Pro

AI: "Log a 30-minute call with John Smith about the Q2 proposal"

The agent calls log_activity with:

{
  "type": "call",
  "contact_id": "John Smith",
  "subject": "Q2 proposal discussion",
  "duration": 30
}

Troubleshooting

"MCP server disabled"

Enable the MCP Server in Settings → External Integrations.

"Invalid API key"

Copy the current API key from Settings → External Integrations → MCP Server and paste it into your AI tool's config as the Bearer token.

"Write operations not allowed"

Turn on the Write permission in Settings → External Integrations → MCP Server.

"PrimeTask is locked"

PrimeTask is sitting on its lock screen, so your agent is waiting. Unlock the app and it carries on from where it stopped, with nothing to restart. To let agents keep working while it's locked, turn that on in Settings → Security. See The PrimeTask Lock Screen above.

"Space access denied"

The active Space isn't in your allowed list. Open Settings → External Integrations → MCP Server → Space Access and add the Space.

"Feature requires PrimeTask Pro"

CRM and Custom Fields tools require Pro. Tasks, projects, focus mode, and time tracking work on every license.

"Needs authentication" error in Claude Code

Use the Streamable HTTP config with mcp-remote - it handles auth correctly. The direct type: "http" format triggers OAuth, which PrimeTask doesn't use.

Connection fails in Claude Code

Tools not showing up

Restart your AI tool after adding or changing the MCP config. Tools are discovered at session start.

Claude Desktop won't connect

If Claude Desktop (or another MCP client) can't reach PrimeTask, work through this once, in order:

It worked before, and stopped after an update

Updating your AI tool can drop the PrimeTask connection or reset where it looks for its config. If task creation suddenly stops after you update Claude Desktop or another client:

After you regenerate the API key

Regenerating your key replaces it immediately, and the old key stops working right away. Any AI tool still using the old key will fail until you update it:

First request fails, then a retry works

If the first thing you ask fails but the same request works on a second try - or the connection seems to drop part-way through a session - that's usually the AI tool re-establishing its link to PrimeTask, most often right at the start of a session. Nothing in PrimeTask is lost. If it keeps happening:

Things worth knowing

Your data stays on your computer

PrimeTask's MCP server runs locally and never sends data to any server. When you connect an AI agent, that agent's cloud model may receive whatever it sends to its provider - that's the agent's business, not PrimeTask's. Read-only mode is the safe default if you're not sure.

Start Read-only, upgrade when ready

Out of the box the server is read-only. Most useful patterns - standups, reviews, triage, research - work in read-only. Turn Write on when you want the agent to actually make changes.

Profiles help small models

A smaller local model doesn't need to see more than 100 tools. Pick a focused profile such as Core Tasks, Projects, or Minimal to improve tool selection. Full is best suited to clients that handle large tool catalogs well.

Audit log is your friend

Every tool call is logged. Review the audit log when you want to know exactly what the agent did, when, and with what parameters.

Disconnect any time

Toggle the server off in Settings and the agent can't reach PrimeTask. No other cleanup needed.

Common questions

Where to go next