IDEA Base Documentation

Everything you need to integrate IDEA Base into your development workflow.

Quick Start

Get up and running in under 2 minutes.

1. Create an account

2. Create an API key

Go to Settings > API Keys and click Create API Key. Save the key — it's only shown once.

3. Install the MCP server

Add IDEA Base to your AI coding tool with one config block:

MCP Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "idea-base": {
      "command": "npx",
      "args": ["-y", "@idea-base/mcp-server"],
      "env": {
        "IDEA_BASE_API_KEY": "ib_your_api_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "idea-base": {
      "command": "npx",
      "args": ["-y", "@idea-base/mcp-server"],
      "env": {
        "IDEA_BASE_API_KEY": "ib_your_api_key_here"
      }
    }
  }
}

Claude Code

Add via the CLI:

claude mcp add idea-base -- npx -y @idea-base/mcp-server \
  --env IDEA_BASE_API_KEY=ib_your_api_key_here

Or add directly to .mcp.json in your project root, using the same format shown for Cursor above.

API Keys

API keys authenticate both the MCP server and direct REST API calls. Keys are prefixed with ib_ and scoped to your account.

Property	Description
Prefix	`ib_` followed by 32 characters
Permissions	Choose `read`, `write`, or both when creating a key. A `read`-only key is rejected with a 403 on any POST/PUT/DELETE — scopes are enforced, not just recorded.
Expiry	Optional. Set in days at creation time.
Revocation	Instant. Revoked keys stop working immediately.

MCP Tools: Projects

Tool	Description	Required Params
`list_projects`	List all projects	None
`get_project`	Get project details	`project_id`
`create_project`	Create a project	`name`
`update_project`	Update project	`project_id`

MCP Tools: Tasks

Tool	Description	Required Params
`list_tasks`	List tasks for a project. Returns compact rows (id, title, status, priority, estimate, time spent, due date and a 160-character description snippet). Optional: `status`, `verbose` (`true` for full rows)	`project_id`
`get_task`	Get full task details, including subtasks, `blocked_by`, the derived `effective_status` / `status_reason`, assignees, tags and recent work notes. This is the full-detail call — `list_tasks` and `search_tasks` return compact rows	`task_id`
`create_task`	Create a task. Optional: `description`, `acceptance_criteria`, `estimated_minutes`, `priority` (0–5), `start_date`, `due_date` (YYYY-MM-DD), `assignee_user_id`, `parent_task_id` (makes it a subtask — one level only, same project)	`project_id`, `title`
`update_task`	Update task details. Same optional fields as `create_task`; pass an empty string to clear a date or unassign. `blocked_by` (array of task ids) replaces the task's dependencies — pass `[]` to clear them; `blocked_reason` is the free-text note shown beside a blocked status	`task_id`
`update_task_status`	Change status: `todo`, `in_progress`, `blocked` or `done`. Optional `blocked_reason`. A task with subtasks or dependencies also has a derived status — see `effective_status` and `status_reason` on `get_task`	`task_id`, `status`
`search_tasks`	Search across projects, ranked title matches first, then description matches, then recency. Returns compact rows (id, title, status, priority, project / product / customer names, estimate, time logged, due date, snippet). Optional: `project_id`, `product_id`, `customer_id`, `status`, `limit`, `verbose` (`true` for full rows)	`query`
`quick_log`	Create + complete + log time	`project_id`, `title`, `minutes`
`add_comment`	Add a customer-visible or internal comment to a task	`task_id`, `comment`
`add_work_note`	Append an internal work note to a task's activity timeline	`task_id`, `note`
`set_resume_context`	Save a "where I left off" note for the next session	`task_id`, `resume_context`

MCP Tools: Time Tracking

Tool	Description	Required Params
`log_time`	Log time to a task	`task_id`, `minutes`
`start_working`	Mark as actively working	`task_id`
`stop_working`	Stop active work	`task_id`

MCP Tools: Products

Tool	Description	Required Params
`list_products`	List all products	None
`get_product`	Get product details	`product_id`
`create_product`	Create a product	`name`
`link_project_to_product`	Link project to product	`product_id`, `project_id`

REST API: Authentication

All API requests require a Bearer token in the Authorization header:

curl https://app.idea-base.us/api/projects \
  -H "Authorization: Bearer ib_your_api_key_here"

Base URL: https://app.idea-base.us/api

REST API: Projects

Method	Endpoint	Description
GET	`/api/projects`	List all projects
POST	`/api/projects`	Create project
GET	`/api/projects/:id`	Get project details
PUT	`/api/projects/:id`	Update project
DELETE	`/api/projects/:id`	Archive project
GET	`/api/projects/:id/tasks`	List project tasks
POST	`/api/projects/:id/tasks`	Create task
POST	`/api/projects/:id/generate-tasks`	AI generate tasks from requirements
POST	`/api/projects/:id/documents`	Upload a requirements doc. `.docx`, `.txt`, `.md`, and text-based `.pdf` are parsed automatically (first 50 pages); an image-only/scanned PDF has no text layer to extract — copy the text in and paste it instead
GET	`/api/projects/health`	Health scores for all projects
GET	`/api/projects/standup`	Standup intelligence (Team+)
GET	`/api/projects/:id/burndown`	Burndown and velocity data
GET	`/api/projects/:id/wrapup`	Weekly wrap-up summary

REST API: Tasks

Method	Endpoint	Description
GET	`/api/tasks/:id`	Get task details
PUT	`/api/tasks/:id`	Update task
DELETE	`/api/tasks/:id`	Delete task
PUT	`/api/tasks/:id/status`	Update task status
POST	`/api/tasks/:id/verify`	AI verify completion
GET	`/api/tasks/search?q=keyword`	Search tasks

REST API: Time Entries

Method	Endpoint	Description
GET	`/api/tasks/:id/time`	List time entries for task
POST	`/api/tasks/:id/time`	Log time entry
DELETE	`/api/time/:id`	Delete time entry
GET	`/api/time/suggestions`	Pending time suggestions

REST API: Reports

Method	Endpoint	Description
GET	`/api/reports/time`	Time reports (group by day/week/month/user/project)
GET	`/api/reports/executive-summary`	AI executive portfolio summary
GET	`/api/projects/:id/time-summary`	Project time summary

GitHub Integration

Connect your GitHub repos to get:

PR and commit linking to tasks
CI status tracking on tasks
Regression detection when PRs affect completed work — automatic on every PR, or trigger a check on demand from a task's linked PR
Time suggestions when PRs are merged
Changelog generation from commits

Set up in Settings > GitHub Integration. Add the webhook URL to your GitHub repo settings.

Notification Webhooks

Send events to Slack, Discord, or custom endpoints when things happen:

Event	Description
`task_created`	New task added
`task_completed`	Task marked done
`task_assigned`	Task assigned to user
`time_logged`	Time entry recorded
`verification_completed`	AI verification finished

Configure in Settings > Notifications.