MCP Server Setup

BeatOS includes a Model Context Protocol (MCP) server that lets AI assistants like Claude, ChatGPT, and other MCP-capable clients manage your tasks, habits, reviews, and more through natural conversation.

Prerequisites

A BeatOS account
An API key (see Authentication)

Quick Setup (Remote — Recommended)

Connect any MCP-capable client directly to BeatOS over HTTPS. No local install needed.

Claude Code / Claude Desktop

Add to your .mcp.json (project-level) or Claude Desktop config:

{
  "mcpServers": {
    "beatos": {
      "type": "http",
      "url": "https://mcp.beatos.app/api/mcp",
      "headers": {
        "Authorization": "Bearer pgtd_your_api_key_here"
      }
    }
  }
}

ChatGPT and other MCP clients

Use these connection details in your client's MCP settings:

Field	Value
Server URL	`https://mcp.beatos.app/api/mcp`
Transport	Streamable HTTP
Auth Header	`Authorization: Bearer pgtd_your_api_key_here`

Replace pgtd_your_api_key_here with your API key from Settings → API Keys. (API keys retain the pgtd_ prefix for backwards compatibility with existing keys.)

Zero Install

The remote MCP endpoint runs on BeatOS's servers — no local build, no Node.js, no cloning. Just add the URL and your API key.

Alternative: Local stdio via npm

For offline work, custom proxying, or clients that don't support HTTP MCP, run the server locally as an npm package. No repo clone required.

# Verify the package is installed and reachable
npx @beatos/mcp-server --help

npx will download and cache the package on first run. Point your MCP client at it:

{
  "mcpServers": {
    "beatos": {
      "command": "npx",
      "args": ["@beatos/mcp-server"],
      "env": {
        "API_BASE_URL": "https://mcp.beatos.app",
        "API_TOKEN": "pgtd_your_api_key_here"
      }
    }
  }
}

To pin a specific version (recommended for stability):

"args": ["@beatos/mcp-server@0.1.0"]

Available Tools

The MCP server exposes 18 tools:

Task Management

Tool	Description
`list_tasks`	List tasks with optional date and completion filters
`create_task`	Create a new task with title, date, urgency, importance
`update_task`	Update task fields
`complete_task`	Mark a task as completed
`delete_task`	Delete a task

Projects

Tool	Description
`list_projects`	List all projects
`create_project`	Create a new project

Habits

Tool	Description
`list_habits`	List all habits
`create_habit`	Create a new habit
`log_habit`	Log a habit completion or skip
`get_habit_streaks`	Get streak data for all habits

Reviews & Analytics

Tool	Description
`list_reviews`	List review entries
`create_review`	Create a weekly or monthly review
`get_dashboard`	Get dashboard statistics

Organization

Tool	Description
`list_buckets`	List life buckets
`list_bottlenecks`	List bottlenecks
`create_bottleneck`	Create a bottleneck

Usage Examples

Once configured, you can interact with BeatOS through your AI assistant:

"Create a task called 'Review Q1 metrics' for tomorrow, marked as Important"

"What habits do I have due today?"

"Run my weekly review"

"Show me my dashboard stats"

"Log my morning meditation habit as complete"

Troubleshooting

API Key Security

Never commit your API key to version control. Use environment variables or a .env file that's in your .gitignore.

"Unauthorized" errors: Verify your API key is valid in Settings → API Keys
Tools not appearing: Restart your AI client after adding/modifying MCP config
Timeout errors: The remote endpoint has a cold-start time of ~2s on first request
Local npx errors: Run npx clear-npx-cache or npm cache clean --force, then retry. Make sure Node 18+ is installed (node --version).