← Marca

Marca MCP

Integration reference

Connect an MCP client to search, save, organize, archive, annotate, and export your Marca library.

Connect

Create an API key in Settings → API Keys, then configure your MCP client with the endpoint and key below. Keep the key private; it grants access to your Marca library.

{
  "mcpServers": {
    "marca": {
      "url": "https://marca.sh/mcp",
      "headers": { "Authorization": "Bearer mca_..." }
    }
  }
}

Protocol and authentication

  • POST https://marca.sh/mcp uses stateless Streamable HTTP with JSON-RPC 2.0.
  • GET is unsupported. Use initialize, tools/list, tools/call, and ping over POST.
  • initialize and tools/list are metadata-only; tools/call requires Authorization: Bearer mca_….
  • Supported MCP protocol versions: 2025-06-18, 2025-03-26, 2024-11-05.
  • Tool-level validation and not-found failures return a successful tools/call result with isError: true; authentication and protocol failures use JSON-RPC errors. Rate-limit headers are returned with authenticated calls.

Important workflows

Annotation counts: get_clip includes an annotation count. Send include_annotation_count: true to list_clips to include it there; search_clips does not support that option.

Archives: only article clips can be archived. request_archive starts capture; use download_archive to check status and obtain the API-key-authenticated REST source path when ready.

Exports: create_export starts a full-account ZIP job. The ZIP is not returned through MCP; sign in to Marca and download it from Settings once the job is ready.

Clips

save_clip

Save a URL as a bookmark or article (optionally with tags and archiving).

Returns

Returns the saved clip, including its assigned ID and tags.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "minLength": 1
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "Bookmark",
        "Article"
      ]
    },
    "tag_list": {
      "type": "string"
    },
    "archive": {
      "type": "boolean"
    },
    "private": {
      "type": "boolean"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
list_clips

List the authenticated user's clips with optional filters and pagination.

Returns

Returns a paginated clip list with page, limit, total, and has_more metadata.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "description": "Full-text search across title, description, and content",
      "type": "string"
    },
    "tag": {
      "description": "Filter to clips with this tag",
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "Bookmark",
        "Article"
      ]
    },
    "private": {
      "description": "Filter by privacy flag",
      "type": "boolean"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "include_annotation_count": {
      "description": "Include the number of annotations on each clip. Defaults to false.",
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
search_clips

Full-text search the user's clips.

Returns

Returns a paginated list of clips matching the required search query.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Search query"
    },
    "tag": {
      "description": "Filter to clips with this tag",
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "Bookmark",
        "Article"
      ]
    },
    "private": {
      "description": "Filter by privacy flag",
      "type": "boolean"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
get_clip

Get a single clip by id, including its tags.

Returns

Returns the requested clip with tags and annotation_count.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric clip id"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
get_clip_content

Read the extracted text of a saved article. Returns a character window with next_offset for paging through long documents.

Returns

Returns an extracted-text window plus offset, next_offset, total_characters, and has_more.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric clip id"
    },
    "offset": {
      "description": "Character offset to read from. Defaults to 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Maximum characters to return. Defaults to 20000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
edit_clip

Update a clip's title, description, and/or tags.

Returns

Returns the updated clip.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "tags": {
      "description": "Replace the clip's tags with this set",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "add": {
      "description": "Tags to add",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "remove": {
      "description": "Tags to remove",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
tag_clip

Add and/or remove tags on a clip.

Returns

Returns the clip after its tags have changed.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "add": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "remove": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
delete_clip

Delete a clip by id.

Returns

Returns deleted: true and the deleted clip ID.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric clip id"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Collections and tags

list_collections

List the user's collections.

Returns

Returns the authenticated user’s collections.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
create_collection

Create a new collection.

Returns

Returns the newly created collection.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "private": {
      "type": "boolean"
    }
  },
  "required": [
    "title"
  ],
  "additionalProperties": false
}
get_collection

Get a collection and a bounded page of its saved clips.

Returns

Returns the collection and its bounded page of saved clips.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric collection id"
    },
    "limit": {
      "description": "Maximum items to return. Defaults to 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "description": "Return items with ids below this cursor.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
add_collection_item

Add a clip to a collection.

Returns

Returns the created collection-item membership.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "clip_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "collection_id",
    "clip_id"
  ],
  "additionalProperties": false
}
remove_collection_item

Remove an item from a collection.

Returns

Returns the removed collection-item membership.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "item_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "collection_id",
    "item_id"
  ],
  "additionalProperties": false
}
delete_collection

Delete a collection and all of its item memberships.

Returns

Returns the deleted collection result.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric collection id"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
list_tags

List the user's tags with usage counts.

Returns

Returns tags with their usage counts.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Annotations

list_annotations

List annotations (highlights) on an article.

Returns

Returns annotations and their latest notes for the article.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "article_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "article_id"
  ],
  "additionalProperties": false
}
add_annotation

Add a highlight/annotation (with optional note) to an article.

Returns

Returns the created annotation and optional note.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "article_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "highlight": {
      "type": "string",
      "minLength": 1,
      "description": "The highlighted text"
    },
    "anchor": {
      "type": "object",
      "properties": {
        "exact": {
          "type": "string",
          "minLength": 1
        },
        "prefix": {
          "type": "string"
        },
        "suffix": {
          "type": "string"
        },
        "startOffset": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "endOffset": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "exact",
        "startOffset",
        "endOffset"
      ],
      "additionalProperties": false
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "article_id",
    "highlight",
    "anchor"
  ],
  "additionalProperties": false
}
delete_annotation

Delete an annotation by id.

Returns

Returns deleted: true and the deleted annotation ID.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Archives

request_archive

Request a full-page HTML archive capture of an article clip.

Returns

Returns the archive record, or a pending status while capture begins.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric clip id"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
download_archive

Get the archive status and download pointer for an article clip.

Returns

Returns archive status and, when applicable, an API-key-authenticated REST download path.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Numeric clip id"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Exports

create_export

Create a portable ZIP export of your Marca account. The ZIP is downloaded from Marca Settings once it is ready.

Returns

Returns the export job, the Settings handoff path, and a status-specific note.

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "include_archives": {
      "description": "Include saved article HTML files when available. Defaults to true.",
      "type": "boolean"
    },
    "include_private": {
      "description": "Include private clips and collections. Defaults to true.",
      "type": "boolean"
    }
  },
  "additionalProperties": false
}