MCP tools reference

This page lists every tool a connected assistant can use, what each one takes and what it returns. You don't need it to use a connector: the assistant picks the tools itself. It's handy when you want to know what an assistant can see, or you're building your own client. To connect an assistant, see Connect your AI.

#How tools answer

• The server is at https://ideabucket.app/mcp (MCP over Streamable HTTP). Sign in with OAuth, or send an access key as Authorization: Bearer ib_….
• Every tool works only with your own ideas. Ideas in the trash are never shown.
• A successful call returns one text block holding JSON, like the examples below. A failed call returns a short plain-text message marked as an error, for example No idea found with id ….
• Tags are sent without the #. A leading # is removed and tags are lowercased, so #Garden and garden mean the same tag. New tags must be single words of letters, numbers, - and _.
• Ids are idea and note UUIDs, as returned by the other tools.
• Dates are ISO 8601 timestamps.

#Ideas in results

Most tools describe ideas the same way:

#Usage limits

Some tools use Idea Bucket's AI service and count toward your hourly allowance, shared with the app:

Over the limit, the tool fails with a message like Hourly limit reached for search and indexing, try again later. See Limits and privacy.

#Reading tools

#search_ideas

Searches your ideas by meaning and keywords, like Find, best matches first. Notes are searched too. Searches active ideas unless you ask for the archive.

Returns the search mode (semantic, or keyword when meaning search isn't available), a count and the ideas, each with a relevance score.

{
  "mode": "semantic",
  "count": 1,
  "ideas": [
    {
      "id": "7c0e5a52-4f1e-4d0a-9a51-2b7f0c3d9e10",
      "content": "Interview a beekeeper for the next episode",
      "tags": ["podcast"],
      "created_at": "2026-09-14T08:12:44.000Z",
      "archived": false,
      "has_notes": true,
      "score": 0.734
    }
  ]
}

#list_recent_ideas

Lists your most recently added ideas, newest first, optionally only those with one tag. With archived: true it lists the archive instead, most recently archived first.

{
  "count": 1,
  "ideas": [
    {
      "id": "1d2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d",
      "content": "Plant garlic along the south fence",
      "tags": ["garden"],
      "created_at": "2026-09-30T17:05:10.000Z",
      "archived": false,
      "has_notes": false,
      "notes_count": 0
    }
  ]
}

#get_idea

Fetches one idea by id, archived or not, with its notes thread, oldest first. Reading an idea this way counts as opening it, for "hasn't been opened" automations.

Each note has:

If the idea was sent to a coding agent, agent_runs lists those runs, newest first: status is awaiting (waiting for your approval), queued or running (being sent), done (sent, with the agent's run_uuid), failed (with error) or skipped (with reason). decided_by says who approved it: you, or assistant:<name>.

{
  "id": "7c0e5a52-4f1e-4d0a-9a51-2b7f0c3d9e10",
  "content": "Interview a beekeeper for the next episode",
  "tags": ["podcast"],
  "created_at": "2026-09-14T08:12:44.000Z",
  "archived": false,
  "notes_count": 1,
  "notes": [
    {
      "id": "b8f1c2d3-4e5f-4a6b-9c7d-8e9f0a1b2c3d",
      "body": "Shortlist: two local keepers. Ask about winter losses.",
      "author": "Claude",
      "author_kind": "assistant",
      "created_at": "2026-09-15T10:00:00.000Z",
      "updated_at": "2026-09-15T10:00:00.000Z",
      "edited": false,
      "yours": true
    }
  ]
}

#list_tags

Lists every tag with how many ideas carry it, most used first, and the color you gave it in the app, if any (blue, teal, green, amber, orange, red, pink or violet). Tags whose ideas are all archived are often finished projects. Takes no parameters.

{
  "ideas": 182,
  "archived_ideas": 64,
  "count": 2,
  "tags": [
    { "tag": "podcast", "open": 21, "archived": 9, "total": 30, "color": "violet" },
    { "tag": "garden", "open": 12, "archived": 3, "total": 15 }
  ]
}

ideas is the number of active ideas in your bucket and archived_ideas the number archived. For each tag, open counts active ideas.

#get_tag_context

Everything about one tag, treated as a project or topic, in one call: what it is, what shipped, what's open, recent activity and related tags. Archived ideas are included, as the project's changelog. Read-only, apart from caching the summary.

If no idea carries the tag, the call fails with No ideas carry #<tag>.

#Status: open, done and closed

Each idea gets a status:

• open: not archived.
• done: archived, and it carries a likely done marker.
• closed: archived without a done marker. It may have shipped or been dropped.

#Likely done markers

No tag means "done" by default, not even #done. Idea Bucket infers done markers from how you archive, and lists each one with its evidence in likely_done_markers. A tag is a likely done marker when either:

• an enabled automation archives ideas that get that tag (On #shipped → Archive), or
• all three of these hold, across your whole bucket:
  • at least 3 ideas carry the tag;
  • at least 80% of them are archived;
  • that share is at least 25 percentage points higher than the archive rate of ideas with your other tags.

Only markers found on this tag's ideas are reported, and nothing is written back to your ideas. Marker tags are left out of related_tags.

#The summary

summary has what_it_is (one or two sentences) and four lists: shipped, open, themes and open_questions. Each list holds up to 6 items, each with text and the ids of the ideas it rests on.

• Written by AI from the tag's newest 80 ideas and their latest notes (source: "ai"), with generated_at and model.
• Template for tags with 2 ideas or fewer: their titles stand in (source: "template"). These don't count toward the summary allowance.
• Cached. The summary is saved and reused (cached: true) until something about the tag's ideas changes: an idea is added, edited, archived, restored, noted or trashed, or the done markers change. The next call then writes a new one. refresh: true forces a new one.
• If a new summary can't be written (for example over the hourly limit), everything else still comes back, with summary_error explaining why. The last saved summary is returned marked stale: true, or summary is null if there isn't one.

#Other fields

{
  "tag": "podcast",
  "counts": { "total": 30, "open": 21, "archived": 9, "done": 6, "closed": 3 },
  "first_activity": "2026-03-02T09:00:00.000Z",
  "last_activity": "2026-09-30T18:20:00.000Z",
  "summary": {
    "what_it_is": "A weekly interview podcast about local food.",
    "shipped": [{ "text": "Season one recorded and released.", "ids": ["3f6a…"] }],
    "open": [{ "text": "Book guests for season two.", "ids": ["7c0e…"] }],
    "themes": [],
    "open_questions": [],
    "source": "ai",
    "cached": true,
    "generated_at": "2026-09-30T18:21:05.000Z",
    "model": "…"
  },
  "recent": [
    { "id": "7c0e…", "title": "Interview a beekeeper for the next episode", "status": "open", "at": "2026-09-30T18:20:00.000Z", "why": "new note" }
  ],
  "changelog": { "total": 9, "items": [ { "id": "3f6a…", "title": "Release season one", "archived_at": "2026-08-01T12:00:00.000Z", "archived_by": "you", "status": "done", "markers": ["shipped"] } ] },
  "open": { "total": 21, "items": [ { "id": "7c0e…", "title": "Interview a beekeeper for the next episode", "tags": [], "last_change": "2026-09-30T18:20:00.000Z", "notes_count": 1 } ] },
  "related_tags": [{ "tag": "garden", "together": 2, "ideas": 15, "archived": 3, "open": 12 }],
  "likely_done_markers": [{ "tag": "shipped", "evidence": "14 of 15 ideas with #shipped are archived (22% of ideas with other tags)" }],
  "more": { "archived": "list_recent_ideas({\"tag\": \"podcast\", \"archived\": true, \"limit\": 50})", "…": "…" }
}

#Writing tools

#add_idea

Saves a new idea. Assistants are told to use it only when you ask to save something. Inline #hashtags in the text become tags and are removed from the text, as in the app.

{
  "saved": true,
  "idea": {
    "id": "1d2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d",
    "content": "Plant garlic along the south fence",
    "tags": ["garden"],
    "created_at": "2026-09-30T17:05:10.000Z",
    "archived": false
  }
}

#update_idea

Changes an existing idea, only when you ask: its text, its tags, or whether it's archived. Pass at least one of content, add_tags, remove_tags or archived. Tags you don't mention are kept.

A tag can't be in both add_tags and remove_tags. An idea archived this way is marked as archived by an assistant.

Returns updated (false when nothing actually changed, for example archiving an idea that's already archived), the idea, and tag_changes when tags were involved: added, removed and not_found (tags you asked to remove that the idea didn't have).

{
  "updated": true,
  "idea": {
    "id": "1d2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d",
    "content": "Plant garlic along the south fence",
    "tags": ["garden", "autumn"],
    "created_at": "2026-09-30T17:05:10.000Z",
    "archived": false,
    "has_notes": false,
    "notes_count": 0
  },
  "tag_changes": { "added": ["autumn"], "removed": [], "not_found": [] }
}

#add_note

Adds a note to an idea: a short Markdown summary of what you and the assistant discussed, such as decisions, next steps or links. You see it in the idea's notes, signed with the assistant's name (or the access key's name). Assistants are asked to read the existing notes with get_idea first and add one note per conversation or topic.

{
  "saved": true,
  "note": {
    "id": "b8f1c2d3-4e5f-4a6b-9c7d-8e9f0a1b2c3d",
    "body": "Shortlist: two local keepers. Ask about winter losses.",
    "author": "Claude",
    "author_kind": "assistant",
    "created_at": "2026-09-15T10:00:00.000Z",
    "updated_at": "2026-09-15T10:00:00.000Z",
    "edited": false,
    "yours": true
  }
}

#edit_note

Replaces the text of a note the same assistant wrote earlier (yours: true in get_idea). An assistant can't edit your notes or another assistant's, and no tool deletes notes: only you can, in the app.

Returns updated (false if the text was the same) and the note, shaped as in add_note.

#dispatch_to_agent

Sends an idea to your coding agent (Grok Bot) through a Dispatch Grok Bot automation, so the agent starts building it. Assistants are told to use it only when you explicitly ask. It approves the dispatch on your behalf, signed with the assistant's name. See Grok Bot dispatch.

• With no Dispatch Grok Bot rule turned on, it fails and says to set one up under Automations.
• With several rules turned on and no rule_id, it sends nothing and returns the rules to choose from (rule_id, tag and the start of the rule's instruction).
• One dispatch per idea and rule: an idea sent before stays sent. You can Retry it in the app.

{
  "dispatched": true,
  "status": "queued",
  "run_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
  "rule": { "id": "0f1e2d3c-4b5a-4968-8776-655443322110", "tag": "build" },
  "decided_by": "assistant:Claude",
  "message": "Sent to the agent. In a few seconds get_idea shows the run_uuid and a \"Sent to Grok Bot\" note; the agent reports back with notes and tags."
}

status is one of queued, running, done (sent earlier), failed (an earlier dispatch failed) or skipped.

#REST endpoints

Two plain HTTP endpoints sit next to the MCP server for simple clients, like the iPhone and Mac apps' extras or your own scripts and shortcuts. They accept only an access key, not an assistant's sign-in.

#POST /mcp/drop

Drops a new idea, as if you'd typed it. Inline #tags become tags.

curl -X POST https://ideabucket.app/mcp/drop \
  -H "Authorization: Bearer ib_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "Try a cold-brew stall at the market #garden"}'

source records where the idea came from. It must include app, and may include url, title and bundle_id. Other fields are refused.

{
  "content": "Read this later #reading",
  "source": { "app": "Safari", "url": "https://example.com/article", "title": "An article" }
}

On success it returns 201 with the new idea's id:

{ "id": "1d2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d" }

#GET /mcp/random

Returns one random active idea (never archived or trashed), or null if your bucket is empty.

curl https://ideabucket.app/mcp/random \
  -H "Authorization: Bearer ib_your_key_here"

{
  "idea": {
    "id": "7c0e5a52-4f1e-4d0a-9a51-2b7f0c3d9e10",
    "content": "Interview a beekeeper for the next episode",
    "tags": ["podcast"],
    "created_at": "2026-09-14T08:12:44.000Z"
  }
}

#Errors

Errors come back as JSON with an error message.