# MCP reference

Run `sponge mcp` to serve the local library over stdio. The server accepts newline-delimited JSON-RPC 2.0 and supports initialization, ping, tool discovery, and tool calls. Standard output carries protocol messages only.

[Connect a coding agent](/docs/agents#connect-an-mcp-client) before using these tools. The server negotiates MCP protocol 2025-06-18, 2025-03-26, or 2024-11-05. Unknown arguments are rejected. Tool failures set `isError: true` and return `{ "code", "hint" }` in their content and structured result. Read tools stay local; saving contacts the source, and queueing or syncing uses the connected Sponge account.

This reference is generated from the tool definitions.

## search_library

Search saved articles, PDFs and media by meaning and keywords (hybrid; falls back to keyword search). Returns item ids for read_item.

Reads the local library.

### Inputs

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What to look for",
      "minLength": 1,
      "maxLength": 4096
    },
    "limit": {
      "type": "integer",
      "description": "Maximum results (default 10)",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

## list_items

List saved items newest first, optionally filtered by reading state or kind, with paging.

Reads the local library.

### Inputs

```json
{
  "type": "object",
  "properties": {
    "reading": {
      "type": "string",
      "description": "Reading state filter",
      "minLength": 1,
      "maxLength": 16,
      "enum": [
        "unread",
        "reading",
        "read"
      ]
    },
    "kind": {
      "type": "string",
      "description": "Item kind filter",
      "minLength": 1,
      "maxLength": 32,
      "enum": [
        "article",
        "pdf",
        "media"
      ]
    },
    "limit": {
      "type": "integer",
      "description": "Page size (default 50)",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "type": "integer",
      "description": "Items to skip",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "additionalProperties": false
}
```

## read_item

Read one item as Markdown or as a summary: digest, excerpt and annotations. Markdown comes as plain text, 40000 characters at a time by default: when the result has a nextOffset, call again with offset set to it for the rest.

Reads the local library.

### Inputs

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Item id",
      "minLength": 1,
      "maxLength": 256
    },
    "format": {
      "type": "string",
      "description": "markdown (default) or summary",
      "minLength": 1,
      "maxLength": 16,
      "enum": [
        "markdown",
        "summary"
      ]
    },
    "offset": {
      "type": "integer",
      "description": "Markdown: the character to start from (default 0); pass the previous nextOffset",
      "minimum": 0,
      "maximum": 100000000
    },
    "maxChars": {
      "type": "integer",
      "description": "Markdown: the most characters to return (default 40000)",
      "minimum": 1,
      "maximum": 200000
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
```

## save_url

Capture a web page into the local library now (like `sponge add URL --wait`). The note, if any, is added as a comment, once: saving the same URL with the same note again adds nothing.

Changes state and may contact a source or the connected account.

### Inputs

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "http(s) URL",
      "minLength": 1,
      "maxLength": 2048
    },
    "note": {
      "type": "string",
      "description": "Optional note",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

## queue_save

Queue a URL in your Sponge account so any connected device captures it on its next sync (needs `sponge login`).

Changes state and may contact a source or the connected account.

### Inputs

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "http(s) URL",
      "minLength": 1,
      "maxLength": 2048
    },
    "note": {
      "type": "string",
      "description": "Optional note",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

## add_highlight

Highlight a verbatim quote from an item, with an optional comment. A quote that appears more than once fails with quote-ambiguous and the number of matches: pass occurrence to choose one.

Changes the local library.

### Inputs

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Item id",
      "minLength": 1,
      "maxLength": 256
    },
    "quote": {
      "type": "string",
      "description": "Exact text from the item (at most 4,000 bytes of UTF-8)",
      "minLength": 1,
      "maxLength": 4000
    },
    "occurrence": {
      "type": "integer",
      "description": "Which match to highlight when the quote repeats: 0 is the first",
      "minimum": 0,
      "maximum": 99999
    },
    "comment": {
      "type": "string",
      "description": "Optional comment",
      "minLength": 1,
      "maxLength": 10000
    }
  },
  "required": [
    "id",
    "quote"
  ],
  "additionalProperties": false
}
```

## add_comment

Add a comment to an item.

Changes the local library.

### Inputs

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Item id",
      "minLength": 1,
      "maxLength": 256
    },
    "body": {
      "type": "string",
      "description": "Comment text",
      "minLength": 1,
      "maxLength": 10000
    }
  },
  "required": [
    "id",
    "body"
  ],
  "additionalProperties": false
}
```

## sync

Sync the library with your Sponge account; if this computer is the account's ingest leader, also capture save requests queued from the web (needs `sponge login`). Summaries are drafted automatically by `sponge sync`, not here.

Changes state and may contact a source or the connected account.

### Inputs

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```