> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spote.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools reference for Spote

> Full reference for all Spote MCP tools: create_note, update_note, get_note, delete_note, search_notes, find_similar, list_recent, list_buckets, and list_tags.

The Spote MCP server exposes tools your AI agent can call during a conversation. All tools require a valid Bearer token in the `Authorization` header. See [Personal Access Tokens](/guides/personal-access-tokens) to create one.

<Note>
  Tags passed to `create_note` should not include the `#` prefix — pass `["project", "ai"]` not `["#project", "#ai"]`. When tags are omitted, Spote extracts them automatically from `#hashtag` syntax in the text.
</Note>

## Note tools

<AccordionGroup>
  <Accordion title="create_note">
    Creates a new note in Spote and indexes it immediately for semantic search. If you omit `tags`, Spote extracts them from any `#hashtag` patterns in the text.

    **Parameters**

    * `title` — string, required. The note title.
    * `text` — string, required. The note body in markdown.
    * `bucket` — string, optional. The folder to save the note in. Defaults to `"Inbox"`.
    * `tags` — string\[], optional. A list of tags without the `#` prefix. If omitted, Spote extracts tags from `#hashtag` syntax in the text.

    **Returns**

    * Note ID
    * URL to the note in the Spote web app
    * Bucket the note was saved to
    * Tags that were applied

    **Example**

    ```
    create_note(
      title="Meeting recap: Q3 planning",
      text="Decided to prioritize the #mcp integration this sprint. Next steps: review API design.",
      bucket="Work"
    )
    ```
  </Accordion>

  <Accordion title="update_note">
    Updates an existing note by ID. Only the fields you provide are changed — omitted fields keep their current values. Updating the text or title also rebuilds the note's semantic embedding.

    **Parameters**

    * `id` — string, required. The ID of the note to update.
    * `title` — string, optional. New title.
    * `text` — string, optional. New markdown body.
    * `bucket` — string, optional. Move the note to a different bucket.
    * `tags` — string\[], optional. Replace the note's tags. Does not merge — the new list replaces the old one.
  </Accordion>

  <Accordion title="get_note">
    Retrieves the full content of a note by ID.

    **Parameters**

    * `id` — string, required. The ID of the note to retrieve.

    **Returns**

    * Title
    * URL to the note
    * Bucket
    * Tags
    * Full markdown text
  </Accordion>

  <Accordion title="delete_note">
    Permanently deletes a note and all of its shares. This action cannot be undone.

    **Parameters**

    * `id` — string, required. The ID of the note to delete.
  </Accordion>

  <Accordion title="list_recent">
    Returns your most recently created or updated notes.

    **Parameters**

    * `limit` — number, optional. How many notes to return. Accepts 1–100. Defaults to `20`.
    * `bucket` — string, optional. Filter results to a specific bucket.

    **Returns**

    A list of notes with ID, title, bucket, and URL for each.
  </Accordion>
</AccordionGroup>

## Search tools

<AccordionGroup>
  <Accordion title="search_notes">
    Searches your notes using semantic similarity. Spote embeds your query and finds notes by meaning — not exact wording.

    **Parameters**

    * `query` — string, required. A natural-language question or topic to search for.

    **Returns**

    Up to 10 notes ranked by semantic similarity, each with ID, title, bucket, and URL.
  </Accordion>

  <Accordion title="find_similar">
    Finds notes that are semantically similar to a given note. Useful for surfacing related ideas and past decisions when you're working on a specific topic.

    **Parameters**

    * `note_id` — string, required. The ID of the note to use as the reference.
    * `limit` — number, optional. How many similar notes to return. Accepts 1–20. Defaults to `5`.

    **Returns**

    A list of similar notes (excluding the reference note itself), with ID, title, and URL.
  </Accordion>
</AccordionGroup>

## Organization tools

<AccordionGroup>
  <Accordion title="list_buckets">
    Returns all bucket names in your Spote account. Use this to see which folders exist before saving a note to a specific bucket.

    **Parameters**

    None.

    **Returns**

    All bucket names as a newline-separated list.
  </Accordion>

  <Accordion title="list_tags">
    Returns all tags you've used across your notes, along with how many notes each tag appears in.

    **Parameters**

    None.

    **Returns**

    All tags with note counts, for example `#project (8)`, one per line.
  </Accordion>

  <Accordion title="relate_notes (preview)">
    Registers a logical link between two notes. This is a preview feature — the link is recorded but graph-based navigation is not yet available in the Spote web app.

    **Parameters**

    * `from_id` — string, required. The ID of the source note.
    * `to_id` — string, required. The ID of the note to link to.
  </Accordion>
</AccordionGroup>