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. Claude Code, Cursor, LM Studio, Claude Desktop, and any other MCP-compatible client - you pick the brain; PrimeTask supplies the hands.

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

Streamable HTTP (recommended):

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

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

This uses mcp-remote as a bridge between the AI tool and PrimeTask's HTTP server. It handles authentication automatically.

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.

Feature Gating

Some tools require a Pro licence.

Tool Catalog & Profiles

PrimeTask exposes up to 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 registered, 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.

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 (100+ tools)

Spaces (4 tools)

Tasks (9 tools)

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

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 (5 tools) - Pro

Name resolution: company_id accepts company name or UUID. project_id for isolated CRM accepts project name or UUID.

CRM - Companies (5 tools) - Pro

CRM - Tasks (4 tools) - Pro

CRM - Activities (3 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
  A[Login] --> B{Auth?}
  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.

Relationship fields support bidirectional links and rollup aggregations (sum, avg, min, max, count) across linked entities.

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.

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.

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.

"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 7B local model doesn't need to see 100+ tools. Pick a smaller profile (Core Tasks, Projects, Minimal) to improve tool-selection accuracy on constrained clients. Claude Code and Claude Desktop handle Full without issue.

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